81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
|
## 设置系统（SettingsSystem）技术说明
|
|||
|
|
|
|||
|
|
目标：提供可跨场景/可持久化的设置系统，并与 Reach UI 设置面板联动（Apply/Reset/ESC）。
|
|||
|
|
|
|||
|
|
### 一、脚本清单（项目侧）
|
|||
|
|
- 数据结构：[SettingsData.cs](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Scripts/Core/SettingsSystem/SettingsData.cs)
|
|||
|
|
- 全局服务：[SettingsService.cs](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Scripts/Core/SettingsSystem/SettingsService.cs)
|
|||
|
|
- 启动引导：[SettingsBootstrap.cs](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Scripts/Core/SettingsSystem/SettingsBootstrap.cs)
|
|||
|
|
- UI 控制器：[SettingsController.cs](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Scripts/UI/Settings/SettingsController.cs)
|
|||
|
|
|
|||
|
|
### 二、持久化文件
|
|||
|
|
- 路径：`Application.persistentDataPath/settings.json`
|
|||
|
|
- 写入：`SettingsService.ApplyAndSave(SettingsData data)`
|
|||
|
|
- 重置：`SettingsService.ResetToDefaults(bool applyAndSave)`
|
|||
|
|
|
|||
|
|
### 三、SettingsData（字段约定）
|
|||
|
|
- `graphics`：
|
|||
|
|
- `fullscreenMode`（FullScreenMode 枚举转 int）
|
|||
|
|
- `resolutionIndex`（Screen.resolutions 的索引；-1 表示不主动改分辨率）
|
|||
|
|
- `qualityLevel`（QualitySettings 索引；-1 表示保持当前）
|
|||
|
|
- `vSync`（bool）
|
|||
|
|
- `targetFps`（int，默认 60；<=0 表示不限制）
|
|||
|
|
- `renderScale`（float，倍率；UI 以百分比显示并换算）
|
|||
|
|
- `msaaSampleCount`（int：1/2/4/8）
|
|||
|
|
- `shadowDistance`（float，允许 0）
|
|||
|
|
- `textureMipmapLimit`（0~3）
|
|||
|
|
- `audio`：
|
|||
|
|
- `master/music/sfx`（0~1 线性值）
|
|||
|
|
- `gameplay`：
|
|||
|
|
- `mouseSensitivity`（float）
|
|||
|
|
- `llmProvider`（int：0=DeepSeek，1=Doubao）
|
|||
|
|
|
|||
|
|
### 四、SettingsService（运行时应用）
|
|||
|
|
核心入口：
|
|||
|
|
- `LoadOrCreate()`：读取 settings.json，不存在则生成默认并写一份
|
|||
|
|
- `ApplyToRuntime(SettingsData data)`：应用到运行时（图形/音频）
|
|||
|
|
- `ApplyAndSave(SettingsData data)`：应用并落盘
|
|||
|
|
|
|||
|
|
图形应用策略（节选）：
|
|||
|
|
- Quality：`QualitySettings.SetQualityLevel(...)`
|
|||
|
|
- VSync：`QualitySettings.vSyncCount`
|
|||
|
|
- FPS：`Application.targetFrameRate`
|
|||
|
|
- Fullscreen/Resolution：`Screen.fullScreenMode` + `Screen.SetResolution(...)`
|
|||
|
|
- URP：通过 `GraphicsSettings.currentRenderPipeline` 强转 `UniversalRenderPipelineAsset`：
|
|||
|
|
- `urp.renderScale`
|
|||
|
|
- `urp.msaaSampleCount`
|
|||
|
|
|
|||
|
|
音频应用策略：
|
|||
|
|
- 若 `AudioMixer` 已配置：把 0~1 映射为 dB（-80~0）写入参数
|
|||
|
|
- 若未配置 AudioMixer：退化为 `AudioListener.volume = master`
|
|||
|
|
|
|||
|
|
AudioMixer 可选配置：
|
|||
|
|
- `SettingsService.ConfigureAudioMixer(AudioMixer mixer, string masterParam, string musicParam, string sfxParam)`
|
|||
|
|
|
|||
|
|
### 五、SettingsBootstrap（场景接入方式）
|
|||
|
|
用途：确保进入任意场景都能自动生成全局系统（DontDestroyOnLoad）。
|
|||
|
|
- 自动生成：
|
|||
|
|
- SettingsService
|
|||
|
|
- UIPanelStack + UIPanelStackInput
|
|||
|
|
- PlayerControlLockService
|
|||
|
|
|
|||
|
|
场景操作：
|
|||
|
|
1. 创建 `_Bootstrap` 空物体
|
|||
|
|
2. 挂 `SettingsBootstrap`
|
|||
|
|
3. 可选：拖入 AudioMixer + 参数名
|
|||
|
|
|
|||
|
|
### 六、SettingsController（UI 绑定与 Apply/Reset/ESC）
|
|||
|
|
用途：把 Reach UI 控件的当前值当作“working copy”，按 Apply 写入 SettingsService。
|
|||
|
|
|
|||
|
|
关键方法：
|
|||
|
|
- `OpenAtIndex(int index)`：显示设置面板并切换到指定页（PanelManager 索引）
|
|||
|
|
- `CloseOrBack()`：关闭面板（丢弃未 Apply 的改动）
|
|||
|
|
- `Apply()`：`SettingsService.ApplyAndSave(working)`
|
|||
|
|
- `ResetToDefaults()`：仅重置 UI/working（是否写盘由用户是否再点 Apply 决定）
|
|||
|
|
|
|||
|
|
Dropdown items 接管策略（用于 Settings Element Dropdown 占位项）：
|
|||
|
|
- `rebuild*Items`：true 时，每次打开都会清空并按脚本重建 items，再 Initialize
|
|||
|
|
|
|||
|
|
初始化顺序防护：
|
|||
|
|
- `delayRefreshOneFrameOnEnable`：延迟一帧再 Refresh，避免 Dropdown 尚未 Initialize 导致空引用
|