Echo/Assets/_Project/Docs/SettingsSystem_Technical_Reference.md

设置系统（SettingsSystem）技术说明

目标：提供可跨场景/可持久化的设置系统，并与 Reach UI 设置面板联动（Apply/Reset/ESC）。

一、脚本清单（项目侧）

• 数据结构：SettingsData.cs
• 全局服务：SettingsService.cs
• 启动引导：SettingsBootstrap.cs
• UI 控制器：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 已配置：把 01 映射为 dB（-800）写入参数
• 若未配置 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 导致空引用