## 设置系统（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 导致空引用