Skip to content

CONFIGURATION.md

Latest commit

 

History

History
326 lines (262 loc) · 11.1 KB

CONFIGURATION.md

File metadata and controls

326 lines (262 loc) · 11.1 KB
Raw

CorePin Configuration

This document describes the persisted configuration contract shared by CorePin.UI, CorePin.Shared, and CorePin.Service.

The active file is:

C:\ProgramData\CorePin\config.json

The UI is the normal configuration author. Manual editing is intended for development and advanced troubleshooting.

Ownership and Compatibility

  • CorePin.Shared\Configuration\CorePinConfig.cs is the authoritative managed model.
  • CorePin.Shared\Configuration\CorePinConfigValidator.cs owns managed validation.
  • CorePin.Service\Config\Config.h and ConfigParsing.cpp contain the native representation and parser used by the service.
  • JSON uses camel-case property names and string enum values.
  • The current schema version is 2. Unsupported versions are rejected.

Any contract change must update the managed model, validator, JSON source generation, native model/parser, examples in this document, and relevant tests together.

Save and Reload Semantics

The UI serializes and validates a complete CorePinConfig, writes it to a temporary file, and atomically replaces config.json. Config writes are serialized within the UI so concurrent operations do not overwrite one another.

The service watches the containing directory for filename, timestamp, and size changes. It waits for a stable file snapshot, checks both last-write time and a content hash, then parses the replacement. A change is acknowledged only after the new config has loaded successfully. Until then, the previous immutable runtime config remains active and the service can retry the replacement.

A successfully reloaded config applies to future process launches. Running managed processes retain the launch snapshot needed to enforce and later restore their original state; editing a profile does not mutate an active game session.

Top-Level Shape

{
  "version": 2,
  "powerPlanSettingsVersion": 4,
  "processorLayout": {},
  "ccdProfiles": [],
  "appProfiles": [],
  "service": {},
  "defaultRestorePlanGuid": null,
  "selectedCorePinPlanGuid": null,
  "selectedPowerPlanProfileId": null,
  "lowLatencyModeEnabled": false,
  "corePinOwnedPlanGuids": [],
  "coreIsolation": {},
  "ui": {}
}

The managed reader tolerates missing or null option groups and collections by using defaults. The UI normally writes the complete shape.

Processor Layout

processorLayout is generated from the detected CPU topology:

{
  "processorName": "Example CPU",
  "logicalProcessorCount": 16,
  "physicalCoreCount": 8,
  "packageCount": 1,
  "cacheGroups": [],
  "cores": []
}

Cache groups can describe cache size, V-Cache presence, preferred workload, clock metadata, logical processors, and processor-group masks. Core records describe each physical core, efficiency class, SMT support, and logical processors. The service needs cache groups but does not consume the managed-only per-core presentation list.

Validation rejects negative counts or processor ids, duplicate logical processors within a list, duplicate processor groups, groups outside the 0..65535 range, and zero or malformed hexadecimal affinity masks.

CPU Profiles

ccdProfiles contains reusable processor selections:

{
  "id": "ccd-0",
  "name": "Cache Group 0",
  "logicalProcessors": [0, 1, 2, 3, 4, 5],
  "groupAffinities": [
    { "group": 0, "mask": "0x000000000000003F" }
  ]
}
Field Meaning
id Stable id referenced by app assignments.
name Unique user-facing name.
logicalProcessors Flat logical-processor ids used where one process affinity mask is sufficient.
groupAffinities Explicit processor-group masks for group-aware systems.

Ids and names must be present, ids must be unique, and a profile must contain at least one logical processor or group affinity. The UI additionally prevents duplicate display names. The native parser derives group masks from logical processors when explicit masks are absent.

App Profiles

appProfiles maps a verified executable to a CPU profile and runtime policy:

{
  "id": "steam:12345",
  "displayName": "Example Game",
  "enabled": true,
  "match": {
    "processName": "ExampleGame.exe",
    "executablePath": "C:\\Games\\Example\\ExampleGame.exe",
    "processNameVerified": true
  },
  "assignment": {
    "ccdProfileId": "ccd-0",
    "priority": "Normal",
    "applyToChildren": false,
    "enforce": true,
    "isolationMode": "Light",
    "closeOtherGameProviders": null,
    "schedulingOwner": "CorePin",
    "vrMode": false,
    "xrRuntimeJsonPath": null
  }
}

id and displayName are required and app ids must be unique. ccdProfileId must reference an existing CPU profile.

The native matcher excludes app profiles with enabled: false. For enabled profiles it first indexes the case-insensitive process name, then requires the observed full executable path to match. Slash direction and ASCII case are normalized. processNameVerified records UI verification state; it does not weaken the service's full-path match.

Assignment Values

Field Default Meaning
ccdProfileId required CPU profile available to CorePin-owned scheduling.
priority Normal Idle, BelowNormal, Normal, AboveNormal, or High.
applyToChildren false Applies eligible behavior to child processes.
enforce false Periodically reapplies affinity/priority that CorePin successfully applied.
isolationMode Off Off, Light, Medium, or Aggressive.
closeOtherGameProviders null Per-game launcher cleanup override; null uses the global setting.
schedulingOwner CorePin Selects CorePin or AMD/Windows scheduling ownership.
vrMode false Enables VR companion-process behavior.
xrRuntimeJsonPath null Optional OpenXR runtime override restored after the session.

Scheduling Ownership

  • CorePin applies the selected CPU profile and the CorePin-owned assignment settings.
  • AmdWindowsWhenActive gives supported AMD/Windows V-Cache scheduling time to establish placement. If expected placement is not detected, CorePin falls back to the assigned CPU profile.
  • AmdWindowsOnly leaves affinity, priority, child handling, enforcement, isolation, and VR companion affinity to Windows/AMD without a CorePin fallback.

Launcher cleanup, UI lifecycle behavior, Smart Background Optimization, and one-shot performance recording are independent of scheduling ownership.

Service Options

{
  "enforcementIntervalSeconds": 10,
  "amdWindowsDetectionSettleSeconds": 30,
  "profilerMaximumDurationMinutes": 240,
  "profilerMaximumFileSizeMegabytes": 256,
  "profilerNotificationSoundsEnabled": false,
  "closeUiWhenGameRunning": false,
  "closeOtherGameProvidersWhenGameRunning": false,
  "smartBackgroundOptimizationEnabled": false
}
Field Default Validation / behavior
enforcementIntervalSeconds 10 At least 1 second.
amdWindowsDetectionSettleSeconds 30 5 through 180 seconds.
profilerMaximumDurationMinutes 240 5 through 1,440 minutes.
profilerMaximumFileSizeMegabytes 256 64 through 2,048 MB.
profilerNotificationSoundsEnabled false Starts the one-shot sound helper at recording start/stop.
closeUiWhenGameRunning false Optional UI memory-saving behavior.
closeOtherGameProvidersWhenGameRunning false Global launcher cleanup default.
smartBackgroundOptimizationEnabled false Enables automatic temporary EcoQoS for suitable background processes.

The service snapshots profiler limits when starting a recording. The first limit reached finalizes the recording normally while the game continues. Changes affect subsequent recordings.

Core Isolation

{
  "defaultMode": "Off",
  "minSystemPhysicalCores": 2,
  "protectGameProcessTree": true,
  "excludedProcesses": [],
  "includedProcesses": []
}

minSystemPhysicalCores must be at least one. Include and exclude entries cannot be empty; the service matcher supports wildcard process names. The service also maintains built-in protections for game-related, active, latency-sensitive, system, anti-cheat, VR-runtime, and configured processes. Original process state is restored after the managed session.

Power-Plan State

The top-level power fields track the user's restore plan, the selected CorePin plan, the logical power-profile choice, low-latency mode, and every plan CorePin owns. powerPlanSettingsVersion is currently 4; incrementing the definition's version causes existing CorePin plans to be rewritten with current settings.

GUID rules:

  • every corePinOwnedPlanGuids value must be valid;
  • selectedCorePinPlanGuid must identify a CorePin-owned plan;
  • defaultRestorePlanGuid, when present, must be valid and must not be owned by CorePin.

These fields should be authored through the UI because incorrect ownership can prevent safe cleanup or restoration.

UI Options

{
  "cpuProfilesInitialized": true,
  "libraryView": {
    "providerFilter": "All providers",
    "sortOption": "Provider",
    "sortDescending": false
  }
}

cpuProfilesInitialized prevents starter profiles from being regenerated after initial setup. The provider filter and sort option must be non-empty. Per-game library data such as hidden state is stored in the UI database, not here.

Performance Recording Request

Arming a recording does not add mutable state to an app profile. The UI writes a separate one-shot request beside config.json:

C:\ProgramData\CorePin\performance-recording-request.json

Current request version: 3.

{
  "version": 3,
  "requestId": "unique-request-id",
  "libraryGameId": "steam:12345",
  "gameName": "Example Game",
  "executablePaths": ["C:\\Games\\Example\\ExampleGame.exe"],
  "applyAssignedProfile": true,
  "armedAtUtc": "2026-08-12T12:00:00+00:00"
}

The service requires an exact case-insensitive normalized path match. It claims a matching request by atomically renaming it to a unique .launching file. If profiler startup fails, RAII claim cleanup restores the request; after the profiler initializes, it deletes the claim. A service restart can recover a valid claim older than five minutes when no pending request exists.

This request version is independent of the main configuration schema and the binary performance-session format.

Manual Inspection and Recovery

Validate the active config with a packaged service binary:

.\artifacts\CorePin\service\CorePin.Service.exe --check-config

Before a manual edit, back up the file and stop the UI so it cannot overwrite the change. Invalid replacements are rejected by the service, but a malformed file can still prevent future UI saves or launches from using the intended settings.

If recovery is necessary:

  1. stop CorePin UI and the service;
  2. back up C:\ProgramData\CorePin;
  3. rename config.json;
  4. start the UI and recreate the desired profiles and settings.

Related Documentation