unity/Docs/Production/LightingOptimizationPlan.md

# 地图真实光影优化计划

2026-11-12。工作区：`D:/vibeCoding/unityRouge/workTree/tree3`；分支：`codex/map-improvement`；审计基线：`0857e29`。本文件保留已确认的实施方案，当前成果与实测数据见 [光影验收记录](../QA/Lighting/Acceptance.md)。

用户已确认采用真实灯光、物体遮挡与动态阴影，在本机以 **1920 × 1080、60 FPS** 验收。方案沿用 Unity `6000.6.8f1`、Built-in 渲染管线，采用 Linear 色彩空间、Standard PBR 材质、真实灯光和几何体投影。

## 效果目标与范围

- 太阳、工业灯具的方向、颜色、照射范围与可见光源一致；货箱、墙体、机甲和运输机产生对应的遮挡与动态投影。
- 机甲在移动、转身、推进、跳跃和切换视角时持续投影。脚部、货箱底部和坡道连接处阴影贴合；高架下方有可信的明暗层次。
- 地面、涂装、裸露金属体现不同的漫反射、金属度和光滑度；阴影中仍能识别敌人、拾取物和通路。
- 导航设备和撤离坪需要照亮周围时配备实际 Light；自发光材质用于灯面显示。阴影验收以实际灯光和几何遮挡计算为依据，脚下黑片或阴影贴花不能代替机甲投影。
- 优先完成直接光与动态阴影。间接光和环境反射使用各自的近似或预计算方案，验收记录明确其更新范围；本计划不承诺完整动态全局光照或实时镜面反射。

## 实施前基线与硬件

下表记录实施前的工程静态审计及本机硬件。实施后的设置、画面与性能以验收记录为准。

| 项目 | 当前事实 | 对计划的影响 |
| --- | --- | --- |
| 渲染管线 | `GraphicsSettings.asset` 未绑定 SRP，包清单未安装 URP/HDRP。 | 在现有 Built-in 上完成首轮优化。 |
| 色彩空间 | `ProjectSettings.asset` 的 `m_ActiveColorSpace` 为 `0`，当前为 Gamma。 | 切换 Linear 后重新校准灯光、代码生成颜色、材质与 UI 显示。 |
| 主光源 | `WarzoneDirector.ResetWorld()` 创建方向光，旋转 `(48, -35, 0)`、强度 `1.7`、暖色，已启用 Soft Shadows。 | 优化已有真实主光和阴影链路。 |
| 画质 | Standalone 默认 Ultra，阴影距离 150 米、4 级联；Medium 是 20 米、低分辨率、硬阴影；Low/Very Low 关闭阴影。 | 重新定义可交付档位，并明确中等画质的实际参数。 |
| 地图生命周期 | 三个入口场景保存 GameSession；地面、掩体、灯光等在运行时创建，`ResetWorld()` 禁用并销毁旧 World 根节点。 | 现有空场景直接烘焙不能覆盖运行时地图；首轮采用实时直接光。 |
| 环境光与雾 | 运行时代码设置 `ambientLight`、雾色和密度，但未显式指定 `ambientMode`；入口场景设置为 Skybox 环境模式。 | 实施时回读有效环境模式，统一天空、环境光、主光与雾，分别校准机库和战区。 |
| 材质与灯条 | `WorldFactory` 使用 Standard，普通表面统一设置 Metallic `0.3`、Glossiness `0.35`；灯条主要设置 Emission，未创建对应局部 Light。 | 按表面类型校准材质，对需要环境照明的关键灯具补齐实际灯光。 |
| 第一人称 | `MechPilot.LateUpdate()` 使用 `visual.gameObject.SetActive(!FirstPerson)`；机体和舱框当前均使用第 8 层。 | 修正隐藏方式，保留世界投影；不能简单剔除整个第 8 层。 |
| 帧率设置 | `GameSession.Awake()` 设置目标 120 FPS，现有常用画质开启 VSync；本机显示输出报告 300 Hz。 | 记录限帧与同步条件，分开判断渲染成本与等待时间。 |
| CPU / 内存 | AMD Ryzen 9 5900HX，8 核 16 线程；系统识别物理内存约 31.4 GiB。 | 以本机为首轮验收设备。 |
| GPU | NVIDIA GeForce RTX 3070 **Laptop GPU**，8192 MiB，NVIDIA 驱动 `581.80`；另有 AMD 核显。 | 独立程序回读实际渲染 GPU、API 和分辨率，确认使用 NVIDIA 显卡。 |
| MCP 状态 | 本次 Unity MCP 实例列表为空。 | 本轮仅作静态规划；后续先完成准确实例绑定、导入和编译检查。 |

代码入口：[WarzoneDirector.cs](../../Assets/Game/Scripts/Runs/WarzoneDirector.cs)、[WorldFactory.cs](../../Assets/Game/Scripts/Combat/WorldFactory.cs)、[MechPilot.cs](../../Assets/Game/Scripts/Mechs/MechPilot.cs)、[GameSession.cs](../../Assets/Game/Scripts/Runs/GameSession.cs)。

## 实施顺序与完成条件

| 阶段 | 工作内容 | 完成条件与产出 |
| --- | --- | --- |
| S0 · 基线 | 绑定 tree3 的准确 Unity `Name@hash`，回读完整工程路径、活动场景、编辑器状态；完成导入与编译检查，隔离存档和 PlayerPrefs；保存现有画面、灯光配置及性能基线。 | 工程身份与数据隔离可核查；同一路线、同一配置有优化前截图及采样。 |
| S1 · 光照基础 | 通过 Unity MCP 设置 Linear；保留现有白昼工业环境，分别校准机库和战区的主光、天空/环境光、雾；检查代码颜色和导入纹理的色彩语义。 | 亮部保留细节，阴影可辨认，天空与主光方向一致；材质及中英 UI 颜色回归通过。 |
| S2 · 真实投影 | 校准主光阴影距离、级联、分辨率、Bias、Normal Bias 和近裁剪；核对 Cast/Receive Shadows；修复第一人称机体隐藏导致投影消失；整理舱框、文字、细小标记的投影策略。 | 两种视角下机甲持续投影；脚部与箱底不悬浮，阴影无明显条纹、漏光和近处跳变。 |
| S3 · 灯具与表面 | 对导航设备、撤离坪和机库代表灯具设置实际局部光，优先受控的 Spot Light；按涂装、裸金属、地面分类调整材质；补充环境反射探针。 | 关键灯具能够照亮邻近物体，遮挡物阻断光线；金属反射与当前位置环境相符；局部灯开关和遮挡对比可复现。 |
| S4 · 间接光样例（有条件） | 当高架下或机库等位置仍缺少间接光层次时，先在一个固定环境区域验证静态烘焙、Light Probes 与反射探针；再决定是否推广。 | 烘焙数据匹配实际场景、布局和加载生命周期；动态机甲跨越明暗区域自然过渡。前置条件不满足时记录延期，避免无效烘焙。 |
| S5 · 性能收敛 | 对三个候选画质档逐项采样，依据实测调整阴影覆盖、局部灯数量和探针更新；定位 CPU、GPU 与同步等待各自成本。 | 本机中等画质代表场景 P95 帧耗时 ≤ 16.7 ms；记录真实参数及未达标项。 |
| S6 · 独立构建验收 | Unity MCP 发起 Windows x64 构建并轮询完成，运行完整产物目录；验证双视角、连续进出战区、回收流程和中英显示。 | 归档画面、构建与 Console 结果、性能采样和回归结论；区分编辑器检查与独立程序实测。 |

S0 → S1 → S2 → S3 是核心效果路径；S4 根据实际画面和固定环境条件决定执行；S5、S6 为交付必需检查。每阶段单独保留差异与回退点，小范围更新现有入口，不运行重建全部原型场景的生成命令。

## 关键实现约束

### Linear、环境与材质

Linear 校准统一处理材质、天空、灯光与纹理采样；代码生成的颜色须核对输入语义，避免重复进行 sRGB/Linear 转换。涂装和非金属表面使用符合其性质的金属度，裸金属单独调整；以标准参考球和同一固定镜头比较结果。UI、世界文字和既有双语颜色同时复查。[Unity 色彩空间说明](https://docs.unity.com/en-us/engine/6000.6/manual/materials-and-shaders/graphics-color/color-spaces/set-project-color-space)

环境光、雾和主光的有效参数由明确配置统一应用；`ResetWorld()` 后检查没有残留旧灯和跨场景参数污染。美术配置沿用 `Assets/Game/Data/`、`Assets/Game/Art/`，按现有生成入口应用，保留碰撞、交互点和资源 GUID。

### 第一人称和近处阴影

优先以缓存的 Renderer 切换投影模式：第三人称正常显示并投影；第一人称使用 `ShadowCastingMode.ShadowsOnly` 保留机体投影。驾驶舱独立处理，防止贴相机的舱框向地图投射不合理的大阴影。该方案在实施时验证与机体动画、部件显隐和相机行为的兼容性。[Unity ShadowsOnly API](https://docs.unity.com/en-us/engine/6000.6/script-reference/unityengine/rendering/shadowcastingmode/shadowsonly)

按机甲约 3.2 米的尺度检查 Bias 与 Normal Bias，覆盖脚底、货箱接地、高架和斜坡。级联用于分配近远处阴影精度；软阴影是阴影图过滤效果，实际质量以近距离和移动画面验收。[Unity 阴影级联说明](https://docs.unity.com/en-us/engine/6000.6/manual/lighting-overview/shadows/shadow-realtime/shadow-cascades)

### 局部灯与反射

有环境照明职责的灯具应在同一位置配置实际 Light；需要遮挡的灯启用阴影并限制影响范围。用更少、范围更准确的灯满足预算；亮面显示使用 Emission，并检查其实际 GI 配置，不能仅凭材质发亮判定它照亮了环境。[Unity Standard 材质与 Emission](https://docs.unity.com/en-us/engine/6000.6/manual/materials-and-shaders/built-in/shader-built-in-birp/shader-standard-shader/standard-shader-material-parameters)

运行时地图生成完成后，由脚本触发环境反射探针捕获，避免创建过早而记录空地图。首轮捕获只包含环境，机甲、敌人等可移动主体不写入长期不更新的环境反射；默认按加载或环境变化触发，测量捕获峰值，避免所有探针每帧重绘。其结果用于环境镜面响应，不作为实时动态镜像验收。[Unity 反射探针性能说明](https://docs.unity.com/en-us/engine/6000.6/manual/lighting-overview/reflections/ref-probe-performance)

### 间接光与当前运行时布局

烘焙前必须把样例区域的固定几何和灯光落实为编辑时可见、具有有效 UV 的场景内容，保存 Lighting Data。静态环境及探针应具有独立于临时 World 根节点的明确生命周期，进入区域时保证环境只创建一次。不得同时保留重复的运行时地面、碰撞体或主光。

移动机甲、敌人、货舱和运输机继续接受实时直接光，并在有效的 Light Probes 范围内采样预计算间接光；需要覆盖地面、高架和轻型机体升空范围。首轮只迁移实际需要的固定区域，并保留搜索点、任务、存档和回收事件编号。[Unity 动态物体与 Light Probes](https://docs.unity.com/en-us/engine/6000.6/manual/lighting-overview/direct-and-indirect-lighting/light-probes/moving-objects)

## 候选画质与性能预算

下表保留起始调参值；基础、中等、增强三档现已实现并完成本机独立采样，实际结果见验收记录。光照真实遮挡与机甲投影是各交付档共同要求。

| 参数 | 基础档 | 中等档（验收档） | 增强档 |
| --- | --- | --- | --- |
| 主光源 | 1 个方向光、硬阴影 | 1 个方向光、软阴影 | 1 个方向光、软阴影 |
| 阴影距离起点 | 35 米 | 60 米 | 100 米 |
| 阴影级联 | 2 | 2，必要时对比 4 | 4 |
| 主光阴影图目标等级 | 1024 | 2048 | 4096 |
| 同时启用的额外投影灯 | 0 | 最多 1 个 Spot | 最多 2 个 Spot |
| 环境反射探针起始分辨率 | 128 | 128–256 | 256 |
| 探针刷新 | 地图生成完成后按需捕获 | 地图生成完成后按需捕获 | 按变化与测量结果限频更新 |

调整现有 QualitySettings 档位时核对 Standalone 默认档，避免仍以 Ultra 代替“中等画质”验收；同步检查 Built-in Forward 的逐像素光数量，保证预算内的关键灯不会意外降级。Low/Very Low 若继续作为交付选项，也须保留受控范围的主光投影。

中等档先以新增光照/阴影的 GPU 增量不超过约 3 ms 作为内部调参预算，同时要求最终整帧 P95 ≤ 16.7 ms。增量预算需由 S0 基线校准，不能由硬件型号推断达标。超预算时依次减少探针刷新、额外投影灯与影响范围、无意义的小物体投影，再调整级联、距离和分辨率，保留机甲及主要掩体的真实投影。

## 验收与记录

### 固定观察位置

1. 机库展示台：三种机体、顶部横梁遮挡、金属反射和首页文字。
2. 战区出生点：顺光、侧光、逆光与远近掩体。
3. 货箱旁：脚部、箱底、遮挡边缘与阴影中敌人辨识。
4. 高架下与坡道：背阴层次、坡面接触、快速移动和阴影级联过渡。
5. 导航设备：灯光关闭、开启、插入遮挡物三组对照，确认真实照明和遮挡。
6. 撤离坪：局部灯、运输机抵达与货舱升空的动态投影。

两种驾驶视角均检查，机甲移动与光源/遮挡变化保留短录屏。三种底盘至少覆盖一次投影与舱内检查；首领和护送阶段追加代表性高负载检查。固定相机、布局/随机种子和分辨率形成前后对照，临时验证改动在记录完成后恢复。

### 性能采样

- 使用本机独立 Windows 程序，记录 CPU、GPU、驱动、图形 API、物理分辨率、渲染分辨率、实际画质、阴影参数、VSync 和帧率上限。确认运行于 RTX 3070 Laptop GPU；使用固定供电与性能模式，并关闭其他游戏或 Unity 测试实例。
- 场景预热 60 秒后，同一固定战斗路线分别以越肩和第一人称采样 120 秒，各重复 3 次。记录各次 P50/P95/P99 帧耗时、CPU/GPU 时间、Draw Calls、阴影成本和内存；加载及探针首次捕获峰值单列。
- 诊断采样固定无 VSync、无限帧条件，以区分渲染成本；60 FPS 体验验收单独记录其实际限帧/同步设置。最终按 [项目规范](ProjectConventions.md) 检查中等画质代表场景的 P95 ≤ 16.7 ms，逐场景、逐视角报告结果。
- 独立程序负责最终帧耗时证据；编辑器 Profiler/Frame Debugger 用于定位 Pass 和灯光成本。拿不到可靠 GPU 时间时明确标记缺项，不从平均 FPS 反推阴影 Pass 耗时。

### 回归与产物

双视角切换、近墙精瞄、移动/跳跃、搜索、跨战区、货舱回收、整机撤离和中英切换保持可用；连续机库 → 战区 → 机库至少 3 次，检查灯光/探针/相机数量和内存趋势，确保无重复环境及残留对象。运行现有相关 EditMode 测试，并通过对应 Unity MCP job 查询到完成。

计划实施后的 QA 进入 `Docs/QA/Lighting/`，包括实际验收结论、Screenshots、TestResults、Logs 和性能原始数据；Windows 完整产物进入 `Builds/Windows/x64/Lighting/`。新增 Unity 配置、材质、探针及其 `.meta` 经 Unity MCP 创建、保存与回读；源码仅作必要的光照入口和显隐修复。机体模型/动画及 UI 的并行改动在集成时逐项核对。

实施状态：S0 的身份绑定、数据隔离和历史基线已归档；控制路线后续修正，未完成同路线的精确光照增量比较。S1–S3 已完成实现与回归，Windows 构建及独立动态阴影对照通过；S5 的三个候选档和中等档正式 6×120 秒无限帧采样均通过，S6 的构建与验证记录已归档。额外 60 FPS 限帧实测平均为 60.01 FPS，但 P95 为 17.23–17.28 ms，严格 16.7 ms 判据未通过并保留原始结果。S4 所需的编辑时固定场景尚未落地，当前采用 Trilight 环境近似与实景反射；后续按静态环境条件推进烘焙与 Light Probes。单独阴影 Pass 耗时、初次捕获峰值及桌面工具未能触发的原生键盘动作均明确列为未验证项。详细完成项、原始数据与范围归档于 [光影验收记录](../QA/Lighting/Acceptance.md)。