godot-genre-stealth

絶対に行わないこと（熟練者向けのアンチパターン）

検知と認識

• 二値の「検知／未検知」判定は絶対に使用せず、距離、光量、速度に基づいて蓄積する段階式の検知メーター（0～100％）を必ず使用してください。
• 大量の視界チェックに標準のRayCast3Dノードは絶対に使用せず、PhysicsServerに対して即座にノードなしでクエリできる**PhysicsDirectSpaceState3D.intersect_ray()**を必ず使用してください。
• AIが固体のジオメトリ越しに視認できる状態には絶対にせず、AIの目とプレイヤーのサンプルポイント（頭、胴体、足）の間でレイキャストを必ず行ってください。
• 可視性の判定に単一のサンプルポイントは絶対に使用せず、遮蔽物に部分的に隠れている場合の検知バグを防ぐため、少なくとも3つのポイント（頭、胴体、足）を必ずサンプリングしてください。
• 固定の「ガード経路」は絶対に使用せず、不審な音や行動を確認するためにガードが巡回ルートを離れる動的な調査を必ず実装してください。
• 視線が通った瞬間に「検知」を絶対に発動せず、プレイヤーが立て直せる「猶予時間」を設けるため、減衰率のある検知メーターを必ず使用してください。
• ナビメッシュ上のランダムな地点が安全だと絶対に決めつけず、脅威の方向へのレイキャストで遮蔽物が視線を確実に遮ることを検証し、カバーポイントの安全性を必ず確認してください。
• レイキャストの除外配列にガード自身のRIDを渡し忘れないでください。省略するとレイがガード自身のボディに当たり、誤った遮蔽が発生します。
• 画面外のガードに複雑なAI検知処理を絶対に実行せず、遠方の敵の負荷の高いロジックを一時停止するため、必ずVisibleOnScreenNotifier3Dを使用してください。

システム全体とワールドのロジック

• 聴覚判定に単純なdistance_to()チェックは絶対に使用せず、壁が音を遮るかどうかを判断するため、ナビゲーション経路に沿った音の伝播距離を必ず計算してください。
• 戦闘をステルスと同等に有効には絶対にせず、ステルスのループを維持するため、「派手な戦闘」によって激しい増援や高致死性の状態が発生するよう必ず設定してください。
• 検知の「理由」を絶対に隠さず、**UIアイコン（?, !）**や音声のセリフ（「今のは何だ？」）で即座にフィードバックしてください。
• intersect_ray()の戻り値を絶対に無視せず、実行時クラッシュを防ぐため、必ず最初にis_empty()を確認してください。
• レイキャストがガード自身に当たらないと絶対に決めつけず、クエリパラメーターからガードのRIDを必ず除外してください。

最適化とパフォーマンス

• AIをプレイヤーのスクリプトに強く結び付けることは絶対にせず、ガードが脆弱な依存関係なしにデコイや死体を認識できるよう、必ずダックタイピング（例：if body.has_method("get_detected")）を使用してください。
• 拠点全体のアラーム発動にハードコードされた配列は絶対に使用せず、ガードを**「guards」グループ**に追加し、動的な通知にはget_tree().call_group()を使用してください。
• AIの状態に標準のStringは絶対に使用せず、高頻度ループでポインターレベルの比較をO(1)で行うため、必ずStringName（&"alert"）を使用してください。
• 大規模なNavigationMeshを同期的にベイクすることは絶対にせず、実行時のベイクでメインスレッドが停止しないよう、必ずuse_async_iterationsを使用してください。
• ゲームプレイ中にNode.find_child()へ依存することは絶対にせず、プレイヤーをO(1)で追跡できるよう、必ずグループまたはエクスポートされた参照を使用してください。
• 無力化されたボディのCollisionShapesを有効なままにすることは絶対にせず、経路探索への干渉を防ぐため、必ず無効にするか「corpse」レイヤーへ移動してください。

---

🛠 熟練者向けコンポーネント（scripts/）

対応するシステムを実装する前に、以下を必ず確認してください：

1. stealth_patterns.gd — 空間ステートを使用したLoS、コーンのDOT、聴覚ヘルパー
2. stealth_ai_controller.gd — 複数サンプルのレイ＋RID除外＋経路長に基づく聴覚判定
3. stealth_vision_cone.gd / vision_cone_3d.gd — コーンの作成

元となる熟練者向けパターン

• stealth_patterns.gd - ノードなしのLoS、コーン判定、AI_Audibleバス、非同期の調査。
• stealth_ai_controller.gd - PhysicsDirectSpaceStateを使用する警戒メーターAI（RayCast3Dノードは使用しません）。

モジュール式コンポーネント

• stealth_vision_cone.gd - 2D／ロジック用の視野コーンヘルパー。
• vision_cone_3d.gd - 3D コーンのデバッグ／クエリ用ヘルパー。
• visibility_manager.gd - プレイヤーの露出／ライトジェムの集約。
• light_detector.gd - ライトプローブ／重複判定による露出。
• sound_occlusion_manager.gd - AI の聴覚向けオクルージョン／バスルーティング。

---

コアループ

1. 隠れる／移動する → 2. 視界と光への露出 → 3. 音の伝播 → 4. 警戒レベルの上昇 → 5. 調査／脱出

判断ツリー

知覚

要件	アクション
LoS ＋自身／プレイヤーの RID を除外	必須 stealth_ai_controller.gd ＋ stealth_patterns.gd
光に応じた検知	visibility_manager.gd ／ light_detector.gd
ジオメトリ越しの聴覚	NavigationServer による経路長（コントローラー）＋ sound_occlusion_manager.gd

モジュールを読み込むタイミング

タスク	読み込むもの
ガード AI の基幹部分	patterns ＋ ai_controller
コーンの作成	vision_cone scripts
プレイヤーのライトジェム	visibility ＋ light_detector
大きなワールドオブジェクトの音	sound_occlusion_manager

スキル本文に視界／警戒／アビリティの長いチュートリアルを貼り付けないでください。判断ツリーはここに保ち、スクリプトを使って実装してください。

スキルチェーン

フェーズ	スキル	目的
1. 物理	godot-raycasting-queries	Space-state LoS
2. ナビゲーション	godot-navigation-pathfinding	調査／経路に基づく聴覚
3. AI	godot-state-machine-advanced	IDLE→ALERT FSM
4. オーディオ	godot-audio-systems	AI_Audible バス
5. バランス調整	godot-monte-carlo-balancer	検知しきい値

よくある落とし穴

落とし穴	解決策
ガードごとに RayCast3D を使う	複数サンプルの intersect_ray ＋ RID 除外
聴覚に distance_to を使う	ナビゲーション経路の長さ
画面外での CPU 使用	VisibleOnScreenNotifier で一時停止

詳細レシピ（必要に応じて）

トピック	リファレンス／スクリプト
設計の柱	design-principles.md
視界／音／光	ai-detection-system.md ＋ stealth_ai_controller.gd
警戒 FSM と UI フィードバック	alert-states.md ＋ visibility_manager.gd
プレイヤーツール（リーン、ガジェット）	player-abilities.md
カバーとエンカウントのレイアウト	level-design.md
UI コミュニケーション	ui-communication.md

リファレンス

段階的開示：特定の API を調査するときに限り公式ドキュメントのリンクを開いてください。関連スキルは、隣接する領域へルーティングするときに読み込み、関連スキル群全体を事前に読み込まないでください。

公式ドキュメント

• レイキャスティング — 多数の AI の視線チェックを行う際に RayCast3D を大量に使わずに済む、ノードによるレイキャストと PhysicsDirectSpaceState3D.intersect_ray() の使い分けです。
• 物理演算の概要 — 視界レイ、聴覚範囲、死体レイヤーをフィルタリングするコリジョンレイヤーとマスクです。
• PhysicsDirectSpaceState3D — 複合的な視界チェックや遮蔽物の確認に使う、ノードを介さない intersect_ray / intersect_shape の仕様です。
• PhysicsRayQueryParameters3D — マスク、除外する RID、衝突フラグを設定し、ガード自身が視線クエリを遮らないようにします。
• ライトとシャドウ — ライトジェムの露出やシャドウレイヤーによる隠れ方を左右する Omni/Spot のエネルギーとシャドウです。
• オーディオバス — 大きな足音や衝撃音を聴覚システムに送るための、AI が聴取する専用バスです。
• ナビゲーションの概要（3D） — 巡回や調査経路に使うリージョン、エージェント、非同期ベイクです。
• ナビゲーションパスの使用 — 単純な distance_to() ではなく、壁を考慮した音の伝わる距離として使うパスの長さです。
• NavigationServer3D — 調査に向かうガードのための map_get_path、ランダムな遮蔽物の位置、回避マスクです。
• グループ — ガード／プレイヤー／ライトのグループと call_group を使い、ハードコードした配列なしで基地全体に警報を伝えます。
• VisibleOnScreenNotifier3D — 画面外では負荷の高い検知を一時停止し、遠くにいる AI が物理演算の予算を消費しないようにします。
• 画面読み取りシェーダー — 視界コーンのフィードバックオーバーレイに使う hint_screen_texture です（Godot 3 の SCREEN_TEXTURE ではありません）。

関連スキル

前提条件

• godot-project-foundations — ガード、ライト、プレイヤーのサンプル位置を設定する前に必要な、シーンツリー、グループ、インポート／プロジェクト設定です。
• godot-physics-3d — 視界レイや聴覚範囲が正しく衝突できるようにする CharacterBody3D、レイヤー／マスク、コリジョン形状です。
• godot-raycasting-queries — このジャンルで毎フレーム必要となる、PhysicsServer のクエリパラメーター、除外する RID、複数サンプルによる視線チェックの手法です。

補完

• godot-navigation-pathfinding — NavigationAgentによるパトロール、ターゲットの調査、壁を考慮した経路長ベースの聴覚。
• godot-ai-navigation — 疑念／警戒のステートマシンに情報を送るFOVセンサーと知覚スタック。
• godot-audio-systems — プレイヤーのSFXバスに依存せず、AIが聞き取れるノイズを実現する3Dストリームとバスレイアウト。
• godot-3d-lighting — 光量検知を公平でわかりやすくするための光エネルギー、影、プローブの設定。
• godot-state-machine-advanced — 場当たり的な文字列比較ではなく、StringNameを使ったIDLE/SUSPICIOUS/ALERTED/COMBATマシン。
• godot-signal-architecture — UI、セリフ、AIを疎結合に保つalert_state_changedシグナルと検知メーターシグナル。
• godot-shaders-basics — プレイヤーが発見された理由を常に把握できる、スクリーンスペースのコーン着色とアウトラインによるフィードバック。
• godot-camera-systems — 画面外のガードの処理負荷を抑える、身を乗り出す／覗き込む動作と視錐台ベースのVisibleOnScreenNotifierによる停止。
• godot-monte-carlo-balancer — 難易度をリリースする前に、検知率、FOVの範囲、聴覚の減衰、見逃し猶予時間をシミュレーションします。

下流／利用側

• godot-genre-horror — 感覚に基づくAIのパターンを再利用する、ストーカーの視野コーン、隠れ場所、疑念メーター。
• godot-combat-system — ALERTED/COMBATによってステルスのループが崩れた際の、致命的なエスカレーションとテイクダウンの猶予時間。

マスター

• godot-master — スキルを横断して探索するためのライブラリルーターと、ミラーされたモジュールのエントリ。