fog-of-war-js-ts

dot-skills Fog of War（JavaScript/TypeScript）のベストプラクティス

JS/TS ゲームにおける戦場の霧と視界システムのパフォーマンスおよび正確性に関するガイドです。FOV に関する代表的な文献（Björn Bergström、Albert Ford、Adam Milazzo）、Red Blob Games、rot.js、MDN/WebGL のレンダリング API をもとにまとめています。8 つのカテゴリにわたる 44 のルールを影響度順に並べ、視界コードの作成、レビュー、リファクタリングに役立てることを目的としています。

適用する場面

次のような場合に、このガイドラインを参照してください。

• グリッドマップや連続マップで視界、射線、タイルの可視性を実装する場合
• 戦場の霧の表示（未探索／探索済み／可視のレイヤー）を作成またはリファクタリングする場合
• 戦場の霧の処理が遅い（毎フレーム再計算する）、視覚的なアーティファクト（ちらつき、光漏れ）が発生する、または大きなマップでメモリ使用量が急増する原因を調べる場合
• 多数のユニット（RTS）や大規模なワールド、ストリーミングされるワールドに対応する場合
• 可視状態や探索済み状態の保存方法とレンダリング方法を選ぶ場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	FOV／視界アルゴリズム	重大	fov-
2	更新スケジュールと差分再計算	重大	update-
3	状態表現とデータ構造	高	state-
4	戦場の霧レイヤーのレンダリング	高	render-
5	メモリと割り当て	中〜高	mem-
6	複数の視点とマップのスケーリング	中	scale-
7	ジオメトリとホットループの計算	中	geo-
8	正確性と視覚的なアーティファクト	低〜中	correct-

クイックリファレンス

1. FOV／視界アルゴリズム（重大）

• fov-recursive-shadowcasting - セルごとのレイを使う FOV ではなく、再帰的シャドウキャスティングを使用する
• fov-symmetric-shadowcasting - 一貫した可視性を得るには、対称シャドウキャスティングを優先する
• fov-octant-transforms - 8 つのループではなく、ルックアップテーブルでオクタントを変換する
• fov-radius-bounded-scan - 視界半径とマップ端の範囲内でスキャンする
• fov-single-ray-los - 2 点間の判定には、視線のレイを 1 本だけ使用する
• 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 - マップの編集をまとめ、影響を受ける視点を 1 回だけ再計算する
• update-merge-explored - 明らかにした領域の可視状態を探索済みに統合し、探索済み状態を再構築しない

3. 状態表現とデータ構造（高）

• state-typed-arrays - オブジェクトの配列ではなく、型付き配列に戦場の霧の状態を保存する
• state-flat-1d-index - ネストした配列ではなく、y*width+x でフラットバッファをインデックスする
• state-three-state-encoding - 3 つの戦場の霧の状態を、1 バイトのビットフラグとして表現する
• state-bitset-layers - ブール値の可視レイヤーにはビットセットを使用する
• state-row-major-iteration - バッファのメモリレイアウトに合わせ、行優先で反復処理する
• state-no-string-keys - タイルごとの可視性に文字列キーのマップを使用しない

4. 霧レイヤーの描画（高）

• render-offscreen-fog-layer - 霧を独立したオフスクリーンレイヤーに描画します
• render-dirty-region-only - 変更された霧の領域だけを再描画します
• render-imagedata-not-fillrect - タイルごとの fillRect ではなく、1つの ImageData として霧を構築します
• render-lowres-soft-upscale - タイル解像度で霧を滑らかに描画し、GPU で拡大します
• render-webgl-texsubimage - WebGL で霧テクスチャの変更された矩形領域だけをアップロードします
• render-fade-alpha-lerp - 視野を再計算するのではなく、アルファ値の線形補間で霧の晴れるアニメーションを行います

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 - チームごとに、参照カウント付きの可視性バッファーを1つ共有します
• 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 - 寛容度モデルを1つ選び、すべての箇所で適用します
• correct-explored-not-overwritten - 可視状態の処理で探索済みレイヤーを上書きしないようにします

使い方

詳しい説明と誤ったコード・正しいコードについては、個々のリファレンスファイルを参照してください。

• まず fov- と update- から始めると、大きな効果が得られます。正しいアルゴリズムを使い、変更時にのみ再計算します。
• セクションの定義 - カテゴリー構成、影響度、実行ライフサイクルの順序について説明します。
• ルールのテンプレート - 新しいルールを追加するためのテンプレートです。

参照ファイル

ファイル	説明
references/_sections.md	カテゴリの定義と影響度の順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンと参照情報