godot-genre-roguelike

絶対に避けること（エキスパート向けのアンチパターン）

生成と乱数

• ランの成否を純粋な乱数に左右させないでください。毎回クリア可能にするため、必ず緩和策（リロール、ショップ、救済タイマー）を用意してください。
• ワールド生成にシードを設定しない乱数を使わないでください。デイリーランやデバッグ用に予測可能なシードを使い、必ず独立したRandomNumberGeneratorを初期化してください。
• 重要なロジックで@GlobalScope.randi()に依存しないでください。グローバル状態の汚染を防ぐため、必ずローカルな乱数インスタンスを使ってください。
• 重要なコンテンツのドロップにArray.pick_random()を使わないでください。統計的に不公平な連続を防ぐため、必ずシャッフルバッグを使ってください。
• メインスレッドで巨大なダンジョンを生成しないでください。コア間で生成を分散し、フレームの停止を防ぐため、必ず**WorkerThreadPool.add_task()またはadd_group_task()**を使ってください。
• バックグラウンドスレッドからSceneTreeにアクセスしないでください。メインスレッドで解析する前に、必ずスレッドセーフなArray/PackedByteArrayにダンジョンデータを生成してください。

データと状態

• セーブスカムを許さないでください。パーマデスを徹底するため、ロード直後にラン中のセーブファイルを必ず削除してください。
• プレイヤーに「世界の果て」を見せないでください。未知の謎を保つため、必ずFog of Warまたは視界を制限するコーンを使ってください。
• 複雑な「Director」のヒューリスティクスを毎フレーム評価しないでください。CPU効率を高めるため、重いペーシングロジックは60〜120フレームに1回だけ実行する**フレーム分割（Engine.get_process_frames()）**を必ず使ってください。
• プロシージャル生成中に、部屋を個別にピクセル単位で移動させないでください。シームレスに部屋を接続するため、事前作成したシーン内の**Marker2D接続ポイント**を使って正確なオフセットを算出してください。
• ランの状態がメタ状態に漏れないようにしてください。RunManagerとMetaManagerには、必ず別々のシングルトンまたはResourceを使ってください。
• メタプログレッションを強力にしすぎないでください（ダメージ+100%など）。スキル重視のプレイを維持するため、強化は控えめ（+5〜15%）にしてください。
• ベースとなるステータスResourceにduplicate(true)を呼び出し忘れないでください。ディープコピーしないと、すべてのエンティティで同じ体力インスタンスが共有されます。
• ランの状態を.tscnファイルに保存しないでください。肥大化を防ぐため、必ずuser://にJSONまたはバイナリ形式でシリアライズしてください。
• グリッドロジックの信頼できる唯一の情報源としてSceneTreeに依存しないでください。グリッドデータは必ず別のDictionaryまたはArrayで管理してください。

グリッドとパフォーマンス

• ナビゲーションの再ベイクを忘れないでください。プロシージャルタイルを配置した後に、必ずNavigationRegion2Dを再ベイクしてください。
• タイルグリッドにAStar2Dを使わないでください。開けた場所でO(1)のクエリと高性能な経路探索を実現するため、**jumping_enabled = true（Jump Point Search）を設定したAStarGrid2D**を必ず使ってください。
• 状態を変更した後にAStarGrid2Dのupdate()を呼び出し忘れないでください。経路探索のクエリが古くならないよう、必ず呼び出してください。
• 離散的なグリッド座標に浮動小数点数（Vector2）を使わないでください。精度のずれを防ぐため、必ずVector2iを使ってください。
• 8方向移動にマンハッタン距離のヒューリスティクスを使わないでください。必ず**HEURISTIC_CHEBYSHEVまたはHEURISTIC_OCTILE**を使ってください。
• GDScriptで各セルの座標（0からW,Hまで）をすべて走査しないでください。タイルへのアクセスを最適化するため、必ずget_used_cells()を使ってください。
• プロシージャルレベルのクリアにfree()を使わないでください。フレーム中のセグメンテーションフォールトを避けるため、必ずqueue_free()を使ってください。
• グリッドに大量の状態変更を即座に通知しないでください。ターンの切り替え時のフレームスパイクを避けるため、必ずcall_deferred()または**call_group_flags**を使ってください。
• 高解像度のFog of Warに負荷の高いTileMapLayerノードを使わないでください。必ずColorRectと、RenderingServer.texture_2d_update()で更新するImageTextureを用いたGPUシェーダーマスクを使ってください。

🛠 エキスパート向けコンポーネント（scripts/）

必須：生成、シードの共有、またはメタアンロックを実装する前に、まず以下をお読みください（インラインのサンプルをそのまま流用しないでください）。

• dungeon_generator_walker.gd — Drunkard's Walk とローカルな RandomNumberGenerator（rng.randi() % n を使用し、Array.pick_random() は使用しないでください）。
• seeded_rng_resource.gd — 共有可能なランやデイリーラン向けのシード永続化。
• meta_progression_manager.gd — 永続的なアンロック用通貨と、セーブの境界（ランの状態との区分）。

1つのタスクのために scripts/ フォルダー全体を読み込まないでください。以下のフェーズに合ったスクリプトのみを開いてください。

エキスパート向けの基本パターン

• meta_progression_manager.gd - 安全なデータ永続化と通貨によるアンロックを備えた、メタプログレッションの基本ロジック。
• roguelike_patterns.gd - ローグライク向けの必須エキスパートスニペット10選（AStar、BSP、WorkerThreadPool、ShuffleBag など）。

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

• dungeon_generator_walker.gd - 手続き型の部屋や洞窟を掘削する Drunkard's Walk アルゴリズム。
• fov_raycast_calculator.gd - 物理サーバークエリを使用した高性能な LOS 判定。
• seeded_rng_resource.gd - 決定論的で共有可能なリプレイ性を実現する RNG 状態の永続化。
• turn_manager_decoupled.gd - エンティティのロジックを分離する、シグナル駆動型のターン調整。
• astar_grid_handler.gd - ローグライクの経路探索を最適化する、特化型 AStarGrid2D ラッパー。
• weighted_loot_table.gd - ドロップ率を制御できる、ネイティブ最適化された重み付きランダムアイテムドロップ。
• json_state_serializer.gd - 手続き型エンティティデータとラン状態の永続的なシリアライズ。
• fog_of_war_masker.gd - TileMapLayer ベースの視界マスキングと発見システム。
• meta_progression_resource.gd - 永続的なゲームアンロックとスキルツリーのデータ分離。
• move_command_object.gd - ターン制アクションを元に戻せるコマンドパターンの実装。
• dungeon_generator.gd - 部屋と通路のレイアウト生成を統括する、上位レベルの手続き型オーケストレーター。
• run_manager.gd - ランのシード、フロア、インベントリのライフサイクルを管理するオートロード（start_run / end_run）。
• director_ai.gd - ペーシングマネージャー — プレイヤーの強さとランの経過時間に基づいてスポーンの強度を調整します。
• room_assembler.gd - プレハブシーンからマーカーを基準に、部屋を手続き的に連結します。
• synergy_manager.gd - レリックタグのシナジーを検出し、累積するモディファイアを適用します。
• example_relic_vampirism.gd - Relic リソースのフック（on_damage_dealt）のサンプル。

コアループ

1. 準備：キャラクターを選択し、メタアップグレードを装備します（meta_progression_resource.gd を参照）。
2. ラン：手続き型生成されたレベルを攻略し（dungeon_generator_walker.gd）、一時的なパワーアップを獲得します。
3. チャレンジ：A* 経路探索（astar_grid_handler.gd）を活用し、難易度が上がり続ける遭遇を生き延びます。
4. 死亡／勝利：ランが終了し、リソースが計算されます。
5. メタプログレッション：リソースを永続的なアンロックに使用します（meta_progression_resource.gd）。
6. 繰り返し：新たな能力を備えて新しいランを開始します。

スキルチェーン

フェーズ	スキル	目的
1. アーキテクチャ	godot-autoload-architecture, godot-state-machine-advanced	ラン状態とメタ状態の境界
2. ワールド生成	godot-procedural-generation, godot-tilemap-mastery	毎回異なるレベルを生成（ウォーカー／BSP／ノイズ）
3. 戦闘	godot-combat-system, godot-ai-navigation	緊張感の高い遭遇戦＋視野／経路探索
4. 成長	godot-inventory-system, godot-resource-data-patterns	ランアイテム／レリック＋型付きリソース
5. 永続化	godot-save-load-systems	メタアンロック＋ラン途中のセーブ削除による不正防止
6. バランス調整	godot-monte-carlo-balancer	勝率とメタレベルの比較、役に立たないアイテムの検出

アーキテクチャの概要

ローグライクでは、ラン状態（一時的）とメタ状態（永続的）を厳密に分離する必要があります。

• ランのライフサイクル／シード：死亡時にリセットされる AutoLoad を用意します。シードには必須の seeded_rng_resource.gd を使用します。ラン中の HP／ゴールドをメタセーブに決して混在させないでください。
• メタアンロック：必須の meta_progression_manager.gd と meta_progression_resource.gd を使用します。永続ボーナスは控えめにします（＋5～15％のみ）。
• シリアライズ：json_state_serializer.gd または user:// の JSON バイナリを推奨します。.tscn をランのセーブデータとして扱わないでください。

主なゲームメカニクス（scripts/ に配置）

プロシージャルダンジョン生成

• 酔歩：必須の dungeon_generator_walker.gd を使用します。ローカルにシードを設定した RandomNumberGenerator を渡し、方向は rng.randi() % directions.size() で決定します（Array.pick_random() は使用しないでください）。
• 重要なドロップ／公平性：roguelike_patterns.gd のシャッフルバッグパターン、または weighted_loot_table.gd の重み付けを使用します。
• BSP／部屋オーケストレーター：dungeon_generator.gd を使用します。より高度な WFC／ノイズについては、関連する godot-procedural-generation を参照してください。
• 生成後の経路探索：astar_grid_handler.gd を使用します。ソリッドセルを編集した後に update() を呼び出してください。ナビメッシュを使用している場合は、NavigationRegion2D を再ベイクします。

レリック、ターン、フォグ、ペース配分

• レリックのフック／シナジータグ：Resource のサブクラスと weighted_loot_table.gd を使用します。在庫管理については関連する godot-inventory-system を参照してください。
• ターン：turn_manager_decoupled.gd と move_command_object.gd を使用します。
• フォグ／視線：fog_of_war_masker.gd と fov_raycast_calculator.gd を使用します。
• ディレクターによるペース配分：Engine.get_process_frames() % N で処理をフレーム単位に分割します（NEVER を参照）。ヒューリスティックを毎フレームの _process 処理に含めないでください。

よくある落とし穴

1. RNG への依存：ランの成否を完全に運任せにしないでください。優れたローグライクでは、プレイヤーのスキルで RNG の悪影響を緩和できます。
2. メタ成長のバランス崩壊：メタアップグレードが強すぎると、ゲームは「勝つために作業を繰り返す」ものになり、「学んで勝つ」ものではなくなります。
3. バリエーション不足：プロシージャル生成の質は、配置するコンテンツの質に左右されます。新鮮さを保つには、部屋、敵、アイテムなど、非常に多くのコンテンツが必要です。
4. セーブによる不正：プレイヤーは死亡を避けるためにゲームを終了しようとします。状態の保存はフロア移動時または終了時だけにし、ロード時にセーブデータを削除します（任意ですが、厳格なローグライクでは標準的です）。

Godot 固有のヒント

• シード付きラン：RandomNumberGenerator は常にシードを指定して初期化します。これにより、プレイヤー同士で特定のランのレイアウトを共有できます。
• ResourceSaver：メタ成長には ResourceSaver を使用します。ただし、深くネストされたリソースの循環参照には注意してください。
• 部屋としてのシーン：「部屋」を個別のシーン（Room1.tscn、Room2.tscn）として作成し、生成したレイアウトにインスタンス化します。これにより、プロシージャルなレイアウト内に手作りならではの品質を取り入れられます。
• ナビゲーション：2D ナビゲーションを使用している場合は、ダンジョンのレイアウトを生成した後、実行時に NavigationRegion2D を再ベイクします。

高度なテクニック

• シナジーシステム：アイテムにタグ（fire、projectile、companion）を付け、タグの組み合わせを確認して、予想外のパワーアップを生み出します。
• ディレクターAI：プレイヤーの体力やストレスを追跡し、スポーン率を動的に調整する、目に見えない「ディレクター」システムです（Left 4 Dead のようなものです）。

深度のある内容を扱う場合、意思決定木やスクリプトカタログの範囲を超えるため、必ず参照してください：roguelike-meta-systems-deep.md。最初の配線作業では読み込まないでください。まずは同梱の scripts/ を使用してください。

リファレンス

段階的開示：特定の API を調査するときにのみ公式ドキュメントへのリンクを開き、関連スキルを読み込むのは同分野の別領域へ案内するときに限ってください。関連スキル全体を事前に読み込まないでください。

公式ドキュメント

• TileMap の使用 — プロシージャルに床や壁を配置する際の TileMapLayer のセル、ソース、実行時の配置について説明します。
• TileMapLayer — walker/BSP による生成や霧の解除後に使用する set_cell / get_used_cells API です。
• AStarGrid2D — ヒューリスティック、斜め移動モード、ソリッドセル編集後の update() を備えたグリッドの経路探索です。
• RandomNumberGenerator — 共有可能なプレイ用のシード付き PCG32 です。グローバルな randi() よりもローカルインスタンスを優先してください。
• WorkerThreadPool — メインスレッドをフリーズさせずに、負荷の高いダンジョン生成を別スレッドに移します。
• 複数スレッドの使用 — WorkerThreadPool／タスクを安全に使用できる状況と、SceneTree の所有権ルールについて説明します。
• スレッドセーフな API — データを別スレッドで生成し、タイルやノードの適用はメインスレッドでのみ行います。
• ゲームの保存 — メタ進行のアンロックや、プレイ途中の削除による不正行為を防ぐための user:// 永続化パターンです。
• リソース — Resource を使ったメタ／プレイデータ、duplicate(true)、.tres／カスタムリソースの保存と読み込みについて説明します。
• シングルトン（AutoLoad） — RunManager と MetaManager を分離し、プレイ中の死亡によって永続的な進行状況が消去されないようにします。
• レイキャスティング — Area2D を大量に使わずに FOV／視線を判定する PhysicsDirectSpaceState クエリです。
• FastNoiseLite — AStarGrid2D で接続性を検証する前に、洞窟風マップ用のノイズフィールドを作成します。

関連スキル

前提条件

• godot-project-foundations — プレイ／メタの分離を行う前に必要な、プロジェクト構成、Autoload、Resource の基礎です。
• godot-tilemap-mastery — TileMapLayer の作成と、プロシージャルジェネレーターが書き込む実行時のセル編集について説明します。
• godot-resource-data-patterns — レリック／メタステータス用の Resource の複製、型付きデータ、保存しやすいスキーマについて説明します。
• godot-autoload-architecture — メタ状態に触れることなくプレイ状態を確実にリセットできる、シングルトンの境界について説明します。

補完

• godot-procedural-generation — このジャンルのダンジョンループに供給する、より高度なWalker／BSP／WFCジェネレーターです。
• godot-navigation-pathfinding — AStarGrid2Dのみを使用しない場合のNavigationRegionの再ベイクと、エージェントの経路探索です。
• godot-combat-system — 自動生成されたフロア内でのヒット／被ダメージ処理パイプラインと、ターン制の遭遇戦です。
• godot-inventory-system — ラン中のバッグ、レリックスロット、戦利品テーブルで使用されるアイテムResourceです。
• godot-save-load-systems — JSON／バイナリ永続化、フロア移行時のセーブ、ロード時のパーマデス削除です。
• godot-signal-architecture — SceneTreeをグリッドの信頼できる唯一の情報源とせずに、ターン／フロア／ランのシグナルを疎結合にする方法です。
• godot-performance-optimization — スレッドプール、GPUフォグマスク、大規模環境でフレーム分割するディレクターのヒューリスティックです。

下流／コンシューマー

• godot-monte-carlo-balancer — シード付きランを通じて、メタレベルに対する勝率、救済タイマー、役に立たないアイテムの検出をシミュレートします。
• godot-genre-action-rpg — ローグライクのラン／メタパターンをよく利用する、アクションRPGの戦闘／成長レイヤーです。

マスター

• godot-master — ライブラリーのルーターであり、スキル横断の探索に使うミラー化されたモジュールエントリーです。