fog-of-war-js-ts

dot-skills 战争迷雾（JavaScript/TypeScript）最佳实践

面向 JS/TS 游戏中战争迷雾和视野系统的性能与正确性指南，内容提炼自经典视野文献（Björn Bergström、Albert Ford、Adam Milazzo）、Red Blob Games、rot.js 以及 MDN/WebGL 渲染 API。共包含 8 个类别的 44 条规则，并按影响排序，用于指导可见性代码的编写、审查和重构。

适用场景

在以下情况下可参考这些指南：

• 为网格地图或连续地图实现视野、视线或地块可见性
• 构建或重构战争迷雾显示（未探索 / 已探索 / 可见图层）
• 排查迷雾更新缓慢（每帧都重新计算）、视觉问题（闪烁、光线泄漏）或大型地图内存暴增
• 将可见性扩展到大量单位（RTS）或大型 / 流式世界
• 选择可见性 / 探索状态的存储与渲染方式

按优先级划分的规则类别

优先级	类别	影响	前缀
1	视野 / 可见性算法	关键	fov-
2	更新调度与增量重算	关键	update-
3	状态表示与数据结构	高	state-
4	迷雾图层渲染	高	render-
5	内存与分配	中高	mem-
6	多观察者与地图扩展	中	scale-
7	几何与热循环数学运算	中	geo-
8	正确性与视觉问题	中低	correct-

快速参考

1. 视野 / 可见性算法（关键）

• fov-recursive-shadowcasting - 使用递归阴影投射，而不是逐格射线式视野算法
• fov-symmetric-shadowcasting - 优先使用对称阴影投射，确保可见性一致
• fov-octant-transforms - 使用查找表变换八分区，而不是编写八个循环
• fov-radius-bounded-scan - 将扫描范围限制在视野半径和地图边缘内
• fov-single-ray-los - 使用单条视线射线进行点对点检查
• fov-dda-continuous - 使用 DDA 网格遍历法遍历连续空间
• fov-visibility-polygon - 计算可见多边形，实现平滑的 2D 迷雾

2. 更新调度与增量重算（关键）

• update-recompute-on-move - 仅在观察者移动时重新计算视野
• update-dirty-flag - 为每个观察者跟踪脏标记和地图版本戳
• update-refcount-visibility - 统计每个地块上的观察者数量，以便增量更新多观察者可见性
• update-delta-not-clear - 输出可见性差异，而不是全部清除后重算
• update-debounce-map-edits - 批量处理地图编辑，并对受影响的观察者只重新计算一次
• update-merge-explored - 随着视野揭示内容，将可见区域合并到已探索区域中，切勿重建已探索区域

3. 状态表示与数据结构（高）

• state-typed-arrays - 使用类型化数组存储迷雾状态，而不是对象数组
• state-flat-1d-index - 使用 y*width+x 索引一维缓冲区，而不是嵌套数组
• state-three-state-encoding - 用一个字节中的位标志编码三种迷雾状态
• state-bitset-layers - 使用位集表示布尔型可见性图层
• state-row-major-iteration - 按行优先顺序迭代，以匹配缓冲区的内存布局
• state-no-string-keys - 避免使用字符串键映射存储逐地块可见性

4. 渲染雾层（高）

• render-offscreen-fog-layer - 将雾渲染到单独的离屏图层
• render-dirty-region-only - 仅重绘脏雾区域
• render-imagedata-not-fillrect - 将雾构建为一个 ImageData，而不是逐个图块调用 fillRect
• render-lowres-soft-upscale - 以图块分辨率渲染柔和的雾，并在 GPU 上放大
• render-webgl-texsubimage - 在 WebGL 中仅上传雾纹理的脏矩形区域
• render-fade-alpha-lerp - 通过线性插值 alpha 值来播放雾显现动画，而不是重新计算 FOV

5. 内存与分配（中高）

• mem-reuse-buffers - 一次性分配雾缓冲区并重复使用
• mem-clear-with-fill - 使用 fill 清除可见缓冲区，而不是重新分配或循环清除
• mem-generation-stamp - 使用代际标记跳过逐帧清除
• mem-bitpack-explored - 将已探索图层打包为位，以节省内存和存档空间
• mem-no-hot-loop-closures - 将分配操作移出 FOV 扫描循环

6. 多观察者与地图扩展（中）

• scale-chunk-large-maps - 将大型地图划分为区块，并仅将活动区块保留在内存中
• scale-shared-team-visibility - 每个队伍共享一个带引用计数的可见性缓冲区
• scale-spatial-partition-edits - 使用空间索引查找受编辑影响的观察者
• scale-gameplay-vs-render-culling - 将游戏玩法可见性与屏幕渲染剔除分开
• scale-cap-recompute-budget - 通过时间预算限制每帧重新计算 FOV 的次数

7. 几何与热循环数学运算（中）

• geo-squared-distance - 比较距离的平方，避免逐格计算平方根
• geo-avoid-modulo-deindex - 直接追踪 x 和 y，而不是通过取模取消索引
• geo-integer-slope-shadows - 使用有理斜率，避免浮点漂移
• geo-avoid-trig-in-loop - 预计算方向，而不是逐格调用三角函数
• geo-radius-shape-choice - 根据所需形状选择半径度量方式

8. 正确性与视觉瑕疵（低中）

• correct-symmetric-walls - 一致地照亮墙面图块，避免面闪烁
• correct-corner-peeking - 妥善处理对角墙角
• correct-permissiveness-model - 选定一种通行宽容度模型并在各处统一应用
• correct-explored-not-overwritten - 绝不让可见性遍历覆盖已探索图层

使用方法

阅读各参考文件，了解完整说明以及错误和正确的代码：

• 从 fov- 和 update- 开始，先了解收益最大的两项：正确的算法，以及仅在发生变化时重新计算。
• 章节定义 - 类别结构、影响级别和执行生命周期顺序。
• 规则模板 - 用于添加新规则的模板。

参考文件

文件	描述
references/_sections.md	类别定义和影响排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息