【性能】增加说明文档

ProjectNLD/AI_Gen_Doc/PerformanceManager动态性能参数接入指南.md

@@ -0,0 +1,236 @@
+# PerformanceManager 动态性能参数接入指南
+
+## 目标
+
+本次仅在 `PerformanceManager` 中开放运行时接口，用于**动态调整并立即生效**以下三个参数：
+
+- `Antialiasing`
+- `EnableBloom`
+- `EnableDOF`
+
+不包含 UI、不包含设置存档、不改现有性能档位表。
+
+---
+
+## 代码位置
+
+文件：`Assets/Code/Scripts/GamePlay/Performance/PerformanceManager.cs`
+
+新增接口：
+
+- `SetRuntimeAntialiasing(int antialiasingType)`
+- `SetRuntimeBloomEnabled(bool enable)`
+- `SetRuntimeDepthOfFieldEnabled(bool enable)`
+- `ApplyRuntimeRenderSettings(int antialiasingType, bool enableBloom, bool enableDepthOfField)`
+
+---
+
+## 接口说明
+
+### 1. 动态设置抗锯齿
+
+```csharp
+PerformanceManager.instance.SetRuntimeAntialiasing(EGameAntialiasingType.FXAA);
+```
+
+作用：
+- 更新 `PerformanceManager.data.antialiasingType`
+- 立即调用现有相机刷新逻辑，使当前主相机生效
+
+可选值：
+
+```csharp
+EGameAntialiasingType.CLOSE
+EGameAntialiasingType.FXAA
+EGameAntialiasingType.TAA
+EGameAntialiasingType.SMAA
+```
+
+---
+
+### 2. 动态设置 Bloom 开关
+
+```csharp
+PerformanceManager.instance.SetRuntimeBloomEnabled(true);
+```
+
+作用：
+- 更新 `PerformanceManager.data.enableBloom`
+- 立即刷新当前 `GlobalVolume`
+
+---
+
+### 3. 动态设置 DOF 开关
+
+```csharp
+PerformanceManager.instance.SetRuntimeDepthOfFieldEnabled(false);
+```
+
+作用：
+- 更新 `PerformanceManager.data.enableDepthOfField`
+- 立即刷新当前 `GlobalVolume`
+
+---
+
+### 4. 批量一次性设置
+
+```csharp
+PerformanceManager.instance.ApplyRuntimeRenderSettings(
+    EGameAntialiasingType.SMAA,
+    true,
+    false);
+```
+
+作用：
+- 一次更新 `Antialiasing / Bloom / DOF`
+- 内部统一刷新相机与后处理
+- 适合“点击应用”或“切换预设方案”时调用
+
+---
+
+## 推荐接入方式
+
+### 场景一：UI 单项切换时即时生效
+
+适合做法：
+
+```csharp
+// 抗锯齿下拉框切换
+PerformanceManager.instance.SetRuntimeAntialiasing(selectedType);
+
+// Bloom Toggle 切换
+PerformanceManager.instance.SetRuntimeBloomEnabled(isOn);
+
+// DOF Toggle 切换
+PerformanceManager.instance.SetRuntimeDepthOfFieldEnabled(isOn);
+```
+
+说明：
+- 用户每改一项就即时生效
+- UI 层不需要自己处理相机或 Volume 刷新
+
+---
+
+### 场景二：多个选项一起改，最后统一应用
+
+适合做法：
+
+```csharp
+PerformanceManager.instance.ApplyRuntimeRenderSettings(
+    selectedAntialiasingType,
+    enableBloom,
+    enableDOF);
+```
+
+说明：
+- 避免 UI 在一次操作里多次触发刷新
+- 更适合“确认/应用”按钮
+
+---
+
+## 注意事项
+
+### 1. 这是运行时修改，不等于存档持久化
+
+这些接口只会修改当前运行中的 `PerformanceManager.data` 并立即刷新表现。
+
+如果后续需要“重启游戏后保留设置”，需要由设置系统额外保存对应值，并在进入游戏后重新调用这些接口恢复。
+
+---
+
+### 2. 不要在动态改单项后立刻再次调用整套 `SetPerformance(...)`
+
+例如：
+
+```csharp
+PerformanceManager.instance.SetRuntimeBloomEnabled(false);
+PerformanceManager.instance.SetPerformance(somePerformanceData);
+```
+
+第二句会用整套性能档位重新覆盖前面的运行时改单项结果。
+
+如果 UI 需要支持“性能档位 + 单项覆盖”，建议流程为：
+1. 先应用基础档位
+2. 再调用单项运行时接口做覆盖
+
+---
+
+### 3. 抗锯齿的最终表现受当前主相机影响
+
+`SetRuntimeAntialiasing` 会刷新当前主相机。
+
+如果调用时主相机尚未创建，或后续发生主相机切换，则以 `PerformanceManager.data.antialiasingType` 为准，在后续自动刷新时继续应用。
+
+---
+
+### 4. Bloom / DOF 依赖场景中的 GlobalVolume
+
+接口内部会查找场景中的 `Volume`。
+
+如果当前场景：
+- 没有 `GlobalVolume`
+- `Volume.profile` 为空
+- `Profile` 中不存在 `Bloom` 或 `DepthOfField` 组件
+
+则不会报致命错误，但也不会看到对应效果。
+
+---
+
+### 5. 当前 `AutoSetGlobalVolume()` 会关闭未明确识别的后处理组件
+
+`PerformanceManager.AutoSetGlobalVolume()` 当前逻辑只显式处理：
+- `Bloom`
+- `ShadowsMidtonesHighlights`
+- `DepthOfField`
+
+其他未识别组件会被自动关闭。
+
+如果后续场景新增新的后处理组件，需要先确认该行为是否符合预期。
+
+---
+
+### 6. 战斗场景可能存在额外抗锯齿覆盖逻辑
+
+当前项目里战斗流程中存在直接关闭抗锯齿的逻辑。
+
+因此如果要在战斗内开放抗锯齿切换，建议在：
+- 主相机创建完成后
+- 战斗场景初始化完成后
+- 或用户点击设置项后
+
+再调用一次 `SetRuntimeAntialiasing(...)`，确保以最新用户选择为准。
+
+---
+
+## 建议给 UI 同事的最小接入结论
+
+### 即时切换型 UI
+直接调用：
+
+```csharp
+SetRuntimeAntialiasing(...)
+SetRuntimeBloomEnabled(...)
+SetRuntimeDepthOfFieldEnabled(...)
+```
+
+### 点击“应用”型 UI
+直接调用：
+
+```csharp
+ApplyRuntimeRenderSettings(...)
+```
+
+---
+
+## 本次改动边界
+
+本次仅提供 `PerformanceManager` 的调用入口，不包含：
+
+- UI 表现层代码
+- 设置数据存档
+- 配置表扩展
+- 新性能档位设计
+- 其他后处理项的动态开关
+
+后续如需持久化，再由设置系统补存储与恢复逻辑即可。
+