Skip to main content
Version: Next (dev)

Applying Settings

All clients (native code, the settings menu and the C# client) go through the same Query / Validate / Apply / Confirm / Revert contract. A change is never written directly into a CVar by the caller.

Apply a draft​

auto& settings = plGameApplication::GetGameApplicationInstance()->GetGameSettings();
auto draft = settings.GetConfirmedSettings();
draft.Insert("Quality.Preset", plString("high"));
draft.Insert("Quality.Overrides", plVariantDictionary());
draft.Insert("Display.FpsCap", plInt32(120));
const plUInt64 token = settings.Apply(draft); // 0 means rejected; inspect GetApplyState()

Requests queue under the service mutex. The application calls Update() once render work has drained. A script or world update must never invoke it directly.

A mutation snapshots the current and delayed CVars, applies the quality bundle, audio and display together, and rolls the whole set back on failure. m_Events emits state transitions after the mutex is released, so an event handler can safely call back into the service.

GetApplyState() returns the countdown and restart state. ResetToDefaults("Audio.") returns a complete draft with only that category reset, and passing an empty category resets everything. GetEffectiveSettings() and GetConfirmedSettings() intentionally differ during previews and session overrides.

Execute() offers the same contract for language bindings. Its structured statuses are InvalidValue, Unsupported, Busy, BackendFailure and SaveFailure.

The confirmation timer​

A change to display mode, resolution, refresh rate or VSync starts a 15-second monotonic confirmation timer. Call Confirm(token) to keep the change or Revert(token) to cancel it.

  • Stale tokens and concurrent Apply requests cannot take ownership of a pending change.
  • The timer keeps running while the world is paused or the menu disappears, so a broken display mode always recovers.
  • A menu's teardown must call Revert for the token it owns.
  • A shutdown or crash leaves the recovery journal in place, and it is honored on the next launch.

Display​

Window modeMeaning
0Fixed window
1Resizable window
2Borderless desktop
3Exclusive fullscreen

A refresh rate of 0 uses the desktop or default rate, and windowed and borderless modes always use the desktop refresh rate. Use GetDisplayModes() for the accepted exclusive-fullscreen tuples. The current Windows exclusive implementation supports only the primary monitor. An FPS cap of 0 means unlimited.

Controls that do not exist for the current window, XR or headless configuration are reported as disabled, with a reason.

If a saved display configuration fails to apply at startup, the game falls back to a 1280x720 window. If rolling back a failed preview also fails, the service retries a safe windowed mode.

Audio​

Master volume and mute target plSoundInterface. The music, effects and dialogue controls require the real sound-group names declared in the project's AudioGroups dictionary. An unavailable audio backend or an unmapped bus reports Unsupported.

The audio singleton can be registered before middleware initialization succeeds. Until the engine audio backend is initialized, audio controls are reported as unavailable, every volume, mute and group write is guarded, and startup audio application stays pending. Waiting does not cause rendering or display settings to be reapplied every frame. A focused regression test exercises startup updates and quality selection with an uninitialized audio singleton.

Accessibility​

Accessibility settings become enabled when their consumers register. UI scale, text scale, subtitles and reduced motion are consumed by GameUI.

plGameSettingsShakeComponent is a supplied example of a gameplay consumer: attach it to a dedicated dynamic camera child and set the amplitude in metres. The player's shake-intensity and reduced-motion settings then control the resulting motion. Games are expected to apply the same preferences to their own subtitle and camera systems.

See Also​