222 lines
9.2 KiB
Markdown
222 lines
9.2 KiB
Markdown
# 71 — SS_SettingsManager
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`GameInstanceSubsystem`
|
||
|
||
### Dependencies
|
||
- [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) — Game instance reference
|
||
- [`BPC_PerformanceScaler`](../10-adaptive/69_BPC_PerformanceScaler.md) — Quality settings bridge
|
||
- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Persist settings
|
||
- [`WBP_SettingsUI`](../06-ui/44_WBP_SettingsUI.md) — UI to read/write settings
|
||
|
||
### Purpose
|
||
Centralized settings manager that stores, applies, and persists all player-configurable game settings including graphics, audio, gameplay, controls, accessibility, and language. Operates as a GameInstanceSubsystem so settings are available before any level loads and persist across level transitions. Provides a unified API for reading and writing settings, with change-notification dispatchers for real-time UI updates.
|
||
|
||
### Enums
|
||
|
||
**ESettingsCategory**
|
||
|
||
| Value | Description |
|
||
|-------|-------------|
|
||
| Graphics | Visual quality settings |
|
||
| Audio | Volume and audio settings |
|
||
| Gameplay | Game behavior settings |
|
||
| Controls | Input bindings |
|
||
| Accessibility | Accessibility options |
|
||
| Language | Localization |
|
||
|
||
**ESettingsType**
|
||
|
||
| Value | Description |
|
||
|-------|-------------|
|
||
| Bool | Yes/no toggle |
|
||
| FloatRange | Slider value (0.0–1.0) |
|
||
| IntRange | Integer slider |
|
||
| Dropdown | Enum or option list |
|
||
| KeyBinding | Rebiddable input |
|
||
| Color | Color picker |
|
||
|
||
### Structs
|
||
|
||
**FSettingsEntry**
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| Category | ESettingsCategory | Grouping |
|
||
| Key | FName | Setting identifier |
|
||
| DisplayName | FText | Localized label |
|
||
| Tooltip | FText | Help text |
|
||
| Type | ESettingsType | Data type |
|
||
| CurrentValue | FString | Current value as string |
|
||
| DefaultValue | FString | Default value |
|
||
| MinValue | Float | For ranges |
|
||
| MaxValue | Float | For ranges |
|
||
| Options | TArray\<FText\> | For dropdowns |
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `SettingsMap` | TMap\<FName, FSettingsEntry\> | All settings by key |
|
||
| `bSettingsLoaded` | Bool | Initialization flag |
|
||
| `PendingApplySettings` | TArray\<FName\> | Settings awaiting apply |
|
||
| `bAutoApply` | Bool | Apply changes immediately |
|
||
|
||
### Functions
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `Initialize` | — | — | Load saved settings, set defaults |
|
||
| `RegisterSetting` | Entry: FSettingsEntry | — | Add setting to registry |
|
||
| `GetSetting` | Key: FName | FSettingsEntry | Retrieve setting |
|
||
| `SetSetting` | Key: FName, Value: FString | — | Update setting value |
|
||
| `SetSettingBool` | Key: FName, Value: Bool | — | Type-safe bool setter |
|
||
| `SetSettingFloat` | Key: FName, Value: Float | — | Type-safe float setter |
|
||
| `SetSettingInt` | Key: FName, Value: Int32 | — | Type-safe int setter |
|
||
| `SetSettingDropdown` | Key: FName, OptionIndex: Int32 | — | Dropdown index setter |
|
||
| `GetSettingBool` | Key: FName | Bool | Type-safe bool getter |
|
||
| `GetSettingFloat` | Key: FName | Float | Type-safe float getter |
|
||
| `GetSettingInt` | Key: FName | Int32 | Type-safe int getter |
|
||
| `GetSettingDropdown` | Key: FName | Int32 | Dropdown index getter |
|
||
| `ResetToDefault` | Key: FName | — | Revert single setting |
|
||
| `ResetCategoryToDefaults` | Category: ESettingsCategory | — | Revert all in category |
|
||
| `ResetAllToDefaults` | — | — | Factory reset settings |
|
||
| `ApplySettings` | — | — | Push pending changes to systems |
|
||
| `ApplyGraphicsSettings` | — | — | Push to PerformanceScaler |
|
||
| `ApplyAudioSettings` | — | — | Push to AudioManager |
|
||
| `ApplyGameplaySettings` | — | — | Push to gameplay systems |
|
||
| `ApplyControlSettings` | — | — | Update input mappings |
|
||
| `ApplyAccessibilitySettings` | — | — | Push to AccessibilityManager |
|
||
| `SaveSettings` | — | — | Persist to SS_SaveManager |
|
||
| `LoadSettings` | — | — | Read from SS_SaveManager |
|
||
| `IsSettingModified` | Key: FName | Bool | Compare to default |
|
||
| `GetAllSettingsInCategory` | Category: ESettingsCategory | TArray\<FSettingsEntry\> | Filter by category |
|
||
| `RegisterDefaultSettings` | — | — | Populate standard settings |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[On GameInstance Init]
|
||
└─► RegisterDefaultSettings()
|
||
└─► LoadSettings() from SS_SaveManager
|
||
└─► ApplySettings() to all systems
|
||
└─► bSettingsLoaded = true
|
||
|
||
[SetSetting]
|
||
└─► Update SettingsMap[Key].CurrentValue = Value
|
||
└─► If Key modified:
|
||
Add to PendingApplySettings
|
||
└─► If bAutoApply:
|
||
ApplySettings()
|
||
└─► Broadcast OnSettingChanged(Key, Value)
|
||
|
||
[ApplySettings]
|
||
└─► ApplyGraphicsSettings():
|
||
Get "ResolutionScale", "ShadowQuality", etc.
|
||
Pass to BPC_PerformanceScaler.SetQualityLevel
|
||
└─► ApplyAudioSettings():
|
||
Get "MasterVolume", "SFXVolume", etc.
|
||
Pass to BPC_AudioManager volume modifiers
|
||
└─► ApplyGameplaySettings():
|
||
Get "InvertLook", "Sensitivity", "FOV"
|
||
Pass to BPC_Movement or BPC_Camera
|
||
└─► ApplyControlSettings():
|
||
Get rebindings, apply to UPlayerInput
|
||
└─► ApplyAccessibilitySettings():
|
||
Pass to BPC_AccessibilitySettings
|
||
└─► Clear PendingApplySettings
|
||
└─► OnSettingsApplied.Broadcast()
|
||
|
||
[SaveSettings]
|
||
└─► Serialize SettingsMap to JSON string
|
||
└─► Pass to SS_SaveManager.SaveString("Settings", JSON)
|
||
└─► OnSettingsSaved.Broadcast()
|
||
|
||
[LoadSettings]
|
||
└─► String = SS_SaveManager.LoadString("Settings")
|
||
└─► If String is empty: return (use defaults)
|
||
└─► Deserialize JSON string into SettingsMap
|
||
└─► For each loaded setting:
|
||
If key exists in map: update CurrentValue
|
||
└─► OnSettingsLoaded.Broadcast()
|
||
|
||
[RegisterDefaultSettings]
|
||
└─► Graphics category:
|
||
ResolutionScale Float 1.0 [0.5–1.5]
|
||
ShadowQuality Int 2 [0–3]
|
||
TextureQuality Int 2 [0–3]
|
||
PostProcessQuality Int 2 [0–3]
|
||
AntiAliasing Dropdown [TSR, TAA, FXAA, Off]
|
||
VSync Bool true
|
||
FrameRateLimit Int 60 [30–240]
|
||
GlobalIllumination Dropdown [Lumen, SSGI, Off]
|
||
MotionBlur Bool true
|
||
DepthOfField Bool true
|
||
FoliageQuality Int 2 [0–3]
|
||
ViewDistance Int 2 [0–3]
|
||
└─► Audio category:
|
||
MasterVolume Float 1.0 [0–1]
|
||
SFXVolume Float 1.0 [0–1]
|
||
MusicVolume Float 0.8 [0–1]
|
||
AmbientVolume Float 0.8 [0–1]
|
||
DialogueVolume Float 1.0 [0–1]
|
||
UIVolume Float 1.0 [0–1]
|
||
SpatialAudio Bool true
|
||
AudioQuality Int 2 [0–3]
|
||
└─► Gameplay category:
|
||
InvertLook Bool false
|
||
SensitivityX Float 0.5 [0–1]
|
||
SensitivityY Float 0.5 [0–1]
|
||
FOV Int 90 [70–120]
|
||
HeadBob Bool true
|
||
AutoPickup Bool true
|
||
CrosshairType Dropdown [Default, Dot, Cross, Off]
|
||
Subtitles Bool true
|
||
└─► Controls category:
|
||
(Key bindings stored separately via UPlayerInput)
|
||
└─► Accessibility category:
|
||
SubtitleSize Int 1 [0–3]
|
||
HighContrastUI Bool false
|
||
ColorBlindMode Dropdown [None, Protanopia, Deuteranopia, Tritanopia]
|
||
TextToSpeech Bool false
|
||
ScreenShakeIntensity Float 1.0 [0–1]
|
||
CameraShake Bool true
|
||
ReducedMotions Bool false
|
||
LargeText Bool false
|
||
└─► Language category:
|
||
Language Dropdown [en, fr, de, es, it, pt, ja, ko, zh]
|
||
```
|
||
|
||
### Event Dispatchers
|
||
|
||
| Name | Payload | Description |
|
||
|------|---------|-------------|
|
||
| `OnSettingChanged` | Key: FName, NewValue: FString | Single setting modified |
|
||
| `OnSettingsApplied` | — | All settings pushed to systems |
|
||
| `OnSettingsSaved` | — | Settings persisted |
|
||
| `OnSettingsLoaded` | — | Settings read from save |
|
||
| `OnCategoryReset` | Category: ESettingsCategory | Category reverted |
|
||
|
||
### Communications With
|
||
|
||
| Target | Method | Why |
|
||
|--------|--------|-----|
|
||
| [`BPC_PerformanceScaler`](../10-adaptive/69_BPC_PerformanceScaler.md) | Cast to player | Graphics settings |
|
||
| [`BPC_AudioManager`](../10-adaptive/66_BPC_AudioManager.md) | Cast to player | Audio settings |
|
||
| [`BPC_Movement`](../02-player/14_BPC_Movement.md) | Cast to player | Gameplay settings |
|
||
| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Persistence |
|
||
| [`WBP_SettingsUI`](../06-ui/44_WBP_SettingsUI.md) | Event | UI read/write |
|
||
| [`BPC_AccessibilitySettings`](72_BPC_AccessibilitySettings.md) | Direct call | Accessibility apply |
|
||
| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | Direct call | Init ordering |
|
||
|
||
### Reuse Notes
|
||
- Settings are stored as FString for maximum flexibility (serialize/deserialize as needed)
|
||
- Type-safe getters/setters handle conversion from FString
|
||
- Auto-apply can be toggled for batch changes vs immediate
|
||
- Default settings registered on initialization serve as fallback
|
||
- All settings are available before any level loads (GameInstanceSubsystem)
|
||
- Language settings trigger UI refresh via OnSettingChanged |