implement-fog-of-war

霧の表現を実装する

霧の表現を共有知覚システムとして構築し、表示レイヤーは控えめに保ちます。

このスキルを使用する場面

• 直交投影またはアイソメトリックの Three.js アクションゲームで、障害物を考慮した霧の表現と視界マスクを実装する場合。
• プレイヤーの角度別視界検索テクスチャと、画面全体に適用するソフトな放射状・壁考慮型の霧シェーダーを構築または調整する場合。
• 視線状の筋、壁の境界がくっきりしすぎる、角度の継ぎ目が目立つなど、霧シェーダーのアーティファクトをデバッグする場合。
• ゲームプレイ上の知覚の真実（非表示の敵のターゲティング、照準選択、HUD の数値、テレグラフ）を霧のピクセル越しに漏らさないよう接続する場合。
• メニュー、インベントリ、レビュー／キャプチャモード、一時停止状態、ステージ遷移など、シーンのライフサイクルと状態に霧を統合し、決定論的な知覚／描画予算テストで検証する場合。
• 霧や知覚に関係のない一般的な Three.js のゲームアーキテクチャ、描画、物理には使用しないでください。その場合は、このリポジトリの web-game-development パックを利用してください。

アーキテクチャを維持する

以下の役割を分離します。

1. 範囲、障害物との交差、ゲームプレイ上の視認性は、決定論的な CPU 知覚処理に担わせます。
2. プレイヤーの角度ごとの可視距離を、固定サイズの検索テクスチャ 1 つにエンコードします。
3. その検索テクスチャを、画面全体に適用する 1 つのシェーダーで、ソフトな放射状かつ壁を考慮した霧に変換します。
4. ゲームプレイでは知覚処理の結果を直接使用し、霧のピクセルから戦闘上の真実を推測しないでください。

アルゴリズムを実装または変更する前に、mechanics.md を読んでください。実績のある障害物モデル、シェーダーの合成方法、調整済みの値、状態ルール、敵の挙動、ライティングの制約、テレメトリーが記録されています。

編集前に調査する

• プレイヤーの位置、カメラ、障害物、シーンのライフサイクル、フレームループ、ターゲティング、敵の知覚、描画レイヤーの正しい情報源を特定します。
• ゲームプレイで使用する地面モデルを確認します。実績のあるコーナー逆投影法は、局所的に水平な平面を前提としています。可視範囲内で標高が変化する場合は、正確な地表または地形の再構築を使用してください。
• 既存のシーンの霧、ポストプロセス、レンダラーの作成、レビュー用モード、メニュー、キャプチャ、遷移、破棄処理を確認します。
• 定数や所有権を変更する前に、現在のテストと最近の霧／知覚関連のコミットを確認します。
• 実行時に障害物の状態が変化するかどうかを確認します。形状が視界判定に適している場合は、ナビゲーションや衝突判定で使われているものと同じ有効な障害物コレクションを再利用します。
• 作業ツリーを早い段階で確認し、無関係な変更を維持します。

依存関係の順に実装する

1. 知覚の真実を定義する

• 各視界遮蔽物を、安定した占有範囲、垂直方向の範囲、有効状態で表現します。
• 3D の視線セグメントまたはレイを、水平な占有範囲と垂直方向の範囲の両方に対して判定します。
• 無効な遮蔽物と、目から対象への視線より低い遮蔽物は無視します。
• 次の機能を公開します。
  • 敵、ターゲティング、攻撃向けの点対点知覚判定。
  • 霧の検索テクスチャ向けの決定論的な角度別距離の設定。
• プレイヤーと敵の範囲は明示的に設定します。遭遇の設計上、敵にプレイヤーの視界の境界より先まで発見させる必要がある場合は、両者の範囲を異なる値にします。

2. 視界の検索テクスチャを作成する

• 距離配列、バイトピクセル配列、データテクスチャは、それぞれ 1 回だけ確保します。
• プレイヤーの目の位置から、水平面上で均等な間隔を持つ一定本数のレイを周囲に向けて飛ばします。
• 衝突距離をプレイヤーの視界半径で正規化し、1 行の赤チャンネルテクスチャに量子化して格納します。
• 線形フィルタリング、水平方向の繰り返しラップ、ミップマップなしを使用し、モバイル／デスクトップそれぞれのレイ数の上限を設けます。
• プレイヤーが一定以上移動した場合、または短い最大間隔に達した場合に更新します。フレームループ内でメモリを確保しないでください。

3. 1 つのソフトオーバーレイを描画する

• クリップ空間の平面を 1 つと、透明なシェーダーマテリアルを 1 つ使用します。
• 4 つのカメラコーナーとの交点から、各フラグメントの地面平面上の位置を再構成します。
• 次の要素を組み合わせます。
  • 内側の明瞭な半径と、外側に向かって柔らかく減衰する放射状の効果。
  • 角度ルックアップからサンプリングした、境界がぼかされた壁の効果。
• 隣り合う角度間で障害物の見え方を滑らかにします。壁のフォグは外側の放射状フォグより弱くし、遮蔽物が不透明な扇形ではなく、空気感として見えるようにします。
• 放射状フォグと障害物フォグを max で合成し、最終的な不透明度に上限を設けます。
• 深度テスト、深度書き込み、トーンマッピングを無効にし、ワールドの後に描画します。
• 2 つ目のレンダラー、レンダーターゲット、コンポーザー、またはレイごとのメッシュは導入しないでください。

4. ゲームプレイに統合する

• シミュレーション上の存在と、表示上の可視性を分けて管理します。
• 未発見の敵の描画可能オブジェクトは、レイヤーまたは表示専用の仕組みで隠します。ルートの可視性がライフサイクルやシミュレーションも制御する場合は、アクターのルートを切り替えないでください。
• 未発見の敵は、ターゲットロック、照準対象の選択、最寄りのターゲット検索、HUD のカウント、プレイヤーからの攻撃対象判定から除外します。
• 未発見の敵の存在が漏れるテレグラフは隠します。
• 敵の追跡開始と攻撃には、それぞれ固有の範囲と、同じ視線判定を使用します。
• 知覚によって対象が無効になったら、アクティブなターゲットロックをすぐに解除します。
• シミュレーションフェーズ内では知覚をキャッシュし、後続のシステムで最新の位置が必要な場合は移動後に更新します。

5. 状態とライフサイクルに統合する

• フォグはゲームプレイ中のみ有効にします。
• 製品で明示的に必要とされていない限り、メニュー、インベントリ、レビュー／キャプチャモード、一時停止中またはプレイ中でない状態、ステージ遷移中は無効にします。
• 状態に応じた早期描画分岐に入る前に無効にし、前のフレームが別の状態に漏れないようにします。
• シーンの大気フォグと戦場のフォグは分けて管理します。
• 終了処理でオーバーレイのジオメトリ、マテリアル、ルックアップテクスチャを破棄します。
• レイの予算、有効状態、範囲、可視の敵、ターゲットの可視性、視線、測定距離について、簡潔なテレメトリを公開します。

適切な順序で調整する

1. 障害物のジオメトリと目の高さを検証します。
2. プレイヤーと敵の範囲を検証します。
3. 完全に明瞭な内側の半径を設定します。
4. 外側の放射状の減衰と最大不透明度を設定します。
5. 壁の境界の柔らかさを設定します。
6. 放射状の筋が消えるまで角度方向の平滑化を加えます。
7. 壁が黒いレイではなく遮蔽として感じられるまで、障害物の暗さを弱めます。
8. 見た目の正しさと実測したパフォーマンスを確認してから、レイの予算を調整します。

ぼかしを増やして不適切な障害物データを隠さないでください。視界境界の弱さを補うために、シーン全体を暗くしないでください。

検証する

完了を宣言する前に、validation.md を読んでください。次を実行します。

• 純粋な知覚テストと不透明度テスト。
• 描画予算の構造的な契約テスト。
• ターゲット設定、レイヤー、ライティング、状態の統合テスト。
• プロジェクトの lint とビルド。
• Codex ブラウザーでの実際のデスクトップおよびモバイルブラウザーチェック。

レビュー用モードでフォグが意図的に無効になっている場合は、通常のゲームプレイで見た目を検証します。静止画だけでなく、動き、カメラの移動、壁の境界、ゲート、継ぎ目、メニュー遷移を確認します。

実証済みの品質を維持する

• 内側のプレイエリアを見やすく保ちます。
• 最大の暗さを控えめに保ちます。
• 壁を柔らかくし、目に見える放射状の筋が出ないようにします。
• 角度の継ぎ目が見えないようにします。
• 動的なゲートと視界を同期させます。
• 敵の視界範囲がプレイヤーの視界範囲を超えても、敵の行動が公平になるようにします。
• 信頼できる可視性モデルを 1 つだけ使用し、上限のあるオーバーレイを 1 つだけ使用します。

参考資料

• 上流ソース：MengTo/Skills — implement-fog-of-war
• references/mechanics.md
• references/validation.md
• agents/openai.yaml