Client Settings

Use this skill when a task adds or changes client-side game settings, project settings UI, local graphics/audio options, or lightweight local preferences.

Human-facing doc: docs/systems/ClientSettingsSystem.md.

Fit Check

Goal	Use
Graphics preset, FPS cap, render resolution, scene/particle quality, HDR, anti-aliasing	ClientSettings.Graphics
Music/effects/voice/microphone volume or enabled state	ClientSettings.Audio
Local project preference such as damage numbers, camera sensitivity, local HUD choice	ClientSettings.Preferences
Cross-device save, currency, inventory, progression, purchase state	CloudData or server-side system, not this skill
Runtime SCE weather, fog, lighting, LightGroup presets	sce-scene-environment

Boundaries

• Put usage under #if CLIENT.
• Validate settings in a separate client process, including a connected client launched by the Headless Editor. PIE does not fully support graphics/audio/preferences persistence or readback; both Game and Device preference scopes are affected. Do not diagnose a standalone-client failure from PIE results alone.
• PIE calls can still change process-wide editor audio, frame rate or anti-aliasing, without guaranteed restoration after stopping. Updated editor binaries warn once per PIE game session on first settings read/write; the warning does not block calls or change existing behavior.
• These settings are local client state. They do not sync to the server and are not gameplay authority.
• There are no change events. Read current values when opening the UI; write values when the user changes or confirms them.
• Do not poll or rewrite settings every frame.
• Do not store secrets, large JSON blobs, progression, payments, inventory, or cross-device data in Preferences.
• Built-in graphics/audio settings share the platform settings store; custom Preferences are project-owned and will not appear automatically in the platform settings panel.

Entry Pattern

#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Graphics.Preset = GraphicsPreset.Balanced;
ClientSettings.Audio.Music.Volume = 70;
ClientSettings.Preferences.SetBool("show_damage_numbers", true);
#endif

Graphics Pattern

Use presets for broad choices, and individual properties for an advanced settings page.

#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Graphics.Preset = GraphicsPreset.High;
ClientSettings.Graphics.RenderResolution = RenderResolutionLevel.High;
ClientSettings.Graphics.SceneQuality = SceneQuality.Ultra;
ClientSettings.Graphics.ParticleQuality = ParticleQuality.High;
ClientSettings.Graphics.HdrEnabled = true;
ClientSettings.Graphics.AntiAliasingEnabled = true;
#endif

Frame-rate cap:

#if CLIENT
ClientSettings.Graphics.MaxFrameRate = 120;

int? cap = ClientSettings.Graphics.MaxFrameRate;
if (cap is null)
{
    // No explicit FPS cap.
}

ClientSettings.Graphics.ClearMaxFrameRate();
// Equivalent: ClientSettings.Graphics.MaxFrameRate = null;
#endif

Rules:

• MaxFrameRate accepts positive integers or null.
• Use ClearMaxFrameRate() or MaxFrameRate = null to remove the explicit cap.
• Do not ask users to pass 0 as a public API pattern; 0 is only the platform storage/runtime sentinel.
• Platform settings UI may only expose fixed FPS choices. If it later saves the same setting, it may clamp arbitrary caps to a supported UI option.
• Individual graphics property writes may mark the graphics preset as GraphicsPreset.Custom.

Audio Pattern

#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Audio.Music.Volume = 60;
ClientSettings.Audio.Effects.Volume = 85;
ClientSettings.Audio.Voice.Enabled = false;

var musicVolume = ClientSettings.Audio.Music.Volume;
var effectsEnabled = ClientSettings.Audio.Effects.Enabled;

ClientSettings.Audio[AudioChannel.Microphone].Enabled = true;
#endif

Rules:

• Volume is 0..100.
• Enabled is the mute/unmute control; do not manually rewrite volume to represent enabled state.
• Use Music for background/cutscene music, Effects for UI, combat, movement, foley, doodad, alert, and normal effect sounds, and Voice for in-game dialogue/voice plus voice chat playback.
• AudioChannel is a player-facing settings group, not the same concept as GameDataSound.Category.
• Do not describe AudioChannel and GameDataSound.Category as multiplicative layers. AudioChannel writes batches of native sound type gains; GameDataSound.Category decides which sound type gain an ActorSound uses.

Preferences Pattern

#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Preferences.SetBool("show_damage_numbers", true);
ClientSettings.Preferences.SetFloat("camera_sensitivity", 0.75f);
ClientSettings.Preferences.SetString("hud_layout", "compact");

var showDamageNumbers = ClientSettings.Preferences.GetBool("show_damage_numbers", defaultValue: true);
var sensitivity = ClientSettings.Preferences.GetFloat("camera_sensitivity", defaultValue: 0.5f);
var hudLayout = ClientSettings.Preferences.GetString("hud_layout", defaultValue: "default");
#endif

Use the default ClientSettingScope.Game for project-specific settings. Use ClientSettingScope.Device only for deliberate device-wide preferences:

#if CLIENT
ClientSettings.Preferences.SetBool(
    "developer_overlay_enabled",
    true,
    ClientSettingScope.Device);
#endif

Key rules:

• Keep keys stable and readable.
• Prefer simple booleans, floats, and short strings.
• Use project-specific names for shared/device keys to avoid collisions.

UI Implementation Checklist

1. Read current settings when the settings panel opens.
2. Bind sliders/toggles/segmented controls to local UI state.
3. Apply settings on user action or confirmation.
4. For FPS, include a "no cap" / "unlimited" choice that calls ClearMaxFrameRate().
5. Re-read settings if the panel is reopened after the platform settings UI may have changed values.

Validation

dotnet build src\GameEntry.csproj -c Client-Debug

Then run the client and verify:

1. Initial UI values match current ClientSettings properties.
2. Changed graphics/audio settings apply in the current client.
3. Settings survive leaving and re-entering the game.
4. Arbitrary FPS caps and ClearMaxFrameRate() behave as expected on the target runtime.

Related

• docs/systems/ClientSettingsSystem.md
• docs/ai/skills/ui-layout-api/SKILL.md
• docs/systems/CloudDataSystem.md
• docs/guides/ClientOnlyDebug.md
• docs/ai/skills/sce-preview-verify/SKILL.md