implement-fog-of-war

实现战争迷雾

将战争迷雾构建为共享的感知系统，并采用克制的呈现层。

适用场景

• 为正交或等距视角的 Three.js 动作游戏实现可感知障碍物的战争迷雾和可见性遮罩。
• 构建或调整玩家的角度可见距离查找纹理，以及全屏柔和径向和感知墙体的迷雾着色器。
• 调试迷雾着色器伪影，例如可见的辐条、生硬的墙体边缘或明显的角度接缝。
• 连接游戏感知逻辑（隐藏敌人的目标选择、瞄准选择、HUD 计数、预警），确保这些信息绝不会透过迷雾像素泄露。
• 将迷雾与场景生命周期和状态集成，包括菜单、物品栏、回放／截图模式、暂停状态和关卡切换，并通过确定性感知／渲染预算测试进行验证。
• 不适用于与迷雾／感知无关的常规 Three.js 游戏架构、渲染或物理问题——请改用此仓库中的 web-game-development pack。

保持架构不变

将以下职责分开：

1. 由确定性的 CPU 感知逻辑处理范围、障碍物相交和游戏可见性。
2. 将玩家各个角度的可见距离编码到一个固定大小的查找纹理中。
3. 由一个全屏着色器根据查找纹理生成柔和的径向迷雾和感知墙体的迷雾。
4. 让游戏逻辑直接使用感知结果；绝不要从迷雾像素推断战斗真相。

实现或更改算法前，请阅读 mechanics.md。其中记录了经过验证的障碍物模型、着色器合成方式、校准数值、状态规则、敌人行为、光照限制和遥测。

修改前先检查

• 找到权威的玩家位置、摄像机、障碍物、场景生命周期、帧循环、目标选择、敌人感知和渲染层。
• 确认游戏的地面模型。经过验证的角点反投影方法假设局部平面水平；如果可见区域内的高度会变化，请使用权威表面数据或地形重建。
• 查找现有的场景迷雾、后期处理、渲染器创建、回放模式、菜单、截图、场景切换和资源释放路径。
• 更改常量或所有权前，先阅读当前测试和近期的迷雾／感知提交。
• 确认障碍物状态是否会在运行时改变。如果现有导航或碰撞使用的活动障碍物集合适合视线检测，请复用它。
• 尽早检查工作区，并保留无关更改。

按依赖顺序实现

1. 定义感知真相

• 使用稳定的占地范围、垂直范围和活动状态来表示每个视线阻挡物。
• 检查 3D 视线线段或射线是否同时与水平占地范围和垂直范围相交。
• 忽略非活动阻挡物，以及低于眼睛到目标视线的掩体。
• 提供：
  • 用于敌人、目标选择和攻击的点到点感知；
  • 用于迷雾查找纹理的确定性角度距离填充。
• 显式设置玩家和敌人的视野范围。遭遇设计需要敌人在玩家揭示边界之外发现玩家时，允许二者范围不同。

2. 构建可见性查找纹理

• 一次性分配距离数组、字节像素和数据纹理。
• 围绕玩家视点，以固定数量均匀间隔的水平射线进行检测。
• 将命中距离除以玩家视野半径进行归一化，并量化到单行红色通道纹理中。
• 使用线性滤波、水平重复环绕、不使用 mipmap，并将射线预算限制在移动端／桌面端的合理范围内。
• 在玩家发生明显移动后或达到较短的最长间隔后刷新。不要在帧循环中分配内存。

3. 渲染一层柔和叠加效果

• 使用一个裁剪空间平面和一个透明着色器材质。
• 根据四个摄像机角点的交点重建每个片段的地平面位置。
• 组合以下效果：
  • 清晰的内半径和柔和的外部径向渐变；
  • 从角度查找表采样的羽化墙壁边界。
• 平滑相邻角度之间的障碍物可见性。墙壁雾效的权重应低于外部径向雾效，让阻挡物呈现出大气感，而非不透明的扇形区域。
• 使用 max 合并径向雾效与障碍物雾效，然后限制最终不透明度。
• 禁用深度测试、深度写入和色调映射；在世界场景渲染后再渲染。
• 不要引入第二个渲染器、渲染目标、合成器或逐射线网格。

4. 集成游戏玩法

• 将模拟中的存在状态与呈现可见性分开处理。
• 通过图层或仅影响呈现的机制隐藏尚未揭示的敌人可渲染对象；如果根节点的可见性也会控制生命周期或模拟，就不要切换根节点的可见性。
• 将尚未揭示的敌人排除在目标锁定、瞄准选择、最近目标搜索、HUD 计数和玩家命中判定之外。
• 隐藏可能暴露不可见敌人位置的预警标记。
• 敌人索敌和攻击应使用各自的射程，并遵循同一套视线判定。
• 感知判定一旦失效，就立即清除当前目标锁定。
• 在同一个模拟阶段内缓存感知结果；移动后，如果后续系统需要当前位置信息，则刷新缓存。

5. 集成状态与生命周期

• 仅在游戏进行中启用战争迷雾。
• 菜单、背包、回顾／录制模式、暂停或非游戏状态以及关卡切换期间都应禁用战争迷雾，除非产品明确要求例外。
• 在任何提前渲染分支之前禁用战争迷雾，避免上一帧的内容泄漏到其他状态。
• 将场景大气雾效与战争迷雾分开处理。
• 拆卸时释放叠加层几何体、材质和查找纹理。
• 发布精简的遥测数据，包括射线预算、启用状态、射程、可见敌人数、目标可见性、视线状态和测量距离。

按正确顺序调整

1. 验证障碍物几何体和眼睛高度。
2. 验证玩家和敌人的射程。
3. 设置完全清晰的内半径。
4. 设置外部径向渐变和最大不透明度。
5. 设置墙边柔化程度。
6. 添加角度平滑，直到射线辐条消失。
7. 降低障碍物阴影的强度，直到墙壁呈现为遮挡效果，而非黑色射线。
8. 只有在视觉效果正确且性能经过测量后，才调整射线预算。

不要用额外模糊来掩盖糟糕的障碍物数据。不要为了弥补可见性边界不明显而调暗整个场景。

验证

在声称完成之前，请阅读 validation.md。运行以下检查：

• 纯感知和不透明度测试；
• 结构性渲染预算约束检查；
• 关于目标选择、图层、光照和状态的集成测试；
• 项目 lint 和构建；
• 在 Codex 浏览器中进行真实桌面和移动浏览器检查。

如果回顾模式会有意禁用战争迷雾，请使用正常游戏流程进行视觉验证。检查运动、摄像机移动、墙边、闸门、接缝和菜单切换，而不只是静态画面。

保持已验证的品质

• 保持内侧游戏区域清晰易读。
• 控制最大暗度，避免过暗。
• 保持墙壁边缘柔和，避免出现明显的径向辐条。
• 确保角度接缝不可见。
• 确保动态闸门与视野同步。
• 即使敌人的视野范围大于玩家的揭示范围，也要确保敌人行为公平。
• 保持一个权威的可见性模型和一个范围受限的叠加层。

参考资料

• 上游源码：MengTo/Skills — implement-fog-of-war
• references/mechanics.md
• references/validation.md
• agents/openai.yaml