godot-turn-system

絶対にしてはいけないこと（エキスパート向けアンチパターン）

順序と決定性

• 行動のたびに行動順を再計算してはいけません。O(n log n) の遅延を防ぐため、ラウンドごとに1回だけ、または速度に関わるステータスが変化したときにのみ厳密にソートしてください。

• イニシアチブの同点判定にランダムな方法を使ってはいけません。決定論的なリプレイを実現するため、必ず2つ目の静的属性（敏捷性、ID、または永続的な「運」）を使ってください。

• 反復処理中に、アクティブな行動順キューを変更してはいけません。必ず duplicate() を反復処理するか、ループの後にキューを変更してください。

• グローバルなターン状態の変更を、即時の call_group() でブロードキャストしてはいけません。数百ユニットへの通知でフレームスパイクが発生しないよう、必ず call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) を使用してください。

• Node 階層を信頼できる唯一の情報源として使ってはいけません。論理的なグリッド座標には、必ず Dictionary の盤面状態を使用してください。

ロジックとアクションエコノミー

• 検証前にアクションポイント（AP）を差し引いてはいけません。不正利用を防ぐため、current_ap -= cost を適用する前に必ず can_perform_action(cost) を呼び出してください。
• フェーズ遷移をハードコード（if phase == 0）してはいけません。ドロー／メイン／エンドフェーズには、必ず enum + match または専用のステートマシンを使用してください。
• 内部クリーンアップの前に「ターン終了」を通知してはいけません。次のターンを通知する前に、必ず AP をリセットし、ステータス効果のターン経過処理を行ってください。
• AP のチェックに浮動小数点数の完全一致（==）を使ってはいけません。堅牢に比較するため、必ず >= または is_equal_approx() を使用してください。

戦術グリッドと UI

• タイルグリッドに汎用の AStar2D を使ってはいけません。経路探索を10倍高速化し、斜め移動をネイティブに処理する AStarGrid2D を必ず使用してください。
• 障害物の状態を変更した後に、AStarGrid2D で update() を呼び出し忘れてはいけません。set_point_solid() を切り替えた場合、次のクエリの前にグリッドを必ず更新してください。
• 入力待ちの while ループでメインスレッドをロックしてはいけません。実行を Tree に戻すため、必ず await キーワードまたはシグナルを使用してください。
• ターンの選択に is_action_pressed() を使ってはいけません。メニュー入力をフレーム単位で確実に処理するには、必ず is_action_just_pressed() を使用してください。
• ネットワークゲームでターンタイムアウトを省略してはいけません。迷惑行為を防ぐため、既定の「パス」アクションを設定したサーバー側タイマーを必ず実装してください。以下の「ネットワーク対応ターンタイムアウト」の推奨パターンを参照してください。

---

意思決定ツリー — ターンモデルを選択する

必要なもの	選択するモデル	必須スクリプト
離散ラウンド（チェス／戦術ゲーム／カードフェーズ）	ラウンド＋イニシアチブキュー＋APフェーズ	turn_system_patterns.gd
連続ゲージ（FF 形式の ATB）	_process でアクターごとにゲージを増加	active_time_battle.gd
タイムライン／CTB、割り込みと予測あり	イベントタイムライン＋予測 UI	timeline_turn_manager.gd

してはいけないこと： 4つ目のモデルをコード内に独自に作らないでください。コーディング前に、対応するスクリプトを読んでください。

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

• turn_system_patterns.gd — match ベースのフェーズマシン、UndoRedo、AStarGrid2D の盤面ヘルパー。
• active_time_battle.gd — ATB ゲージ、準備完了時の一時停止、非同期のアクション引き渡し。
• timeline_turn_manager.gd — 割り込みと事前視覚化に対応したタイムライン／CTB。
• turn_predictor.gd — タイムライン UI のプレビュー用に ATB ゲージをシミュレートします。
• combat_stats_resource.gd — ホバー UI 用の決定論的なダメージプレビューリソース。

TurnManager Autoload — インターフェース仕様のみ

Autoload は薄く保ってください。キュー計算の全コードをここに貼り付けず、上で選んだスクリプトに実装してください。

# turn_manager.gd (AutoLoad) — contract only
extends Node
signal turn_started(combatant: Node)
signal turn_ended(combatant: Node)
signal round_ended
signal turn_timed_out(combatant: Node)  # multiplayer: server default-pass

func start_combat(participants: Array[Node]) -> void: pass
func end_turn() -> void: pass
func request_pass(combatant: Node) -> void: pass  # default action on timeout

ネットワーク対応のターンタイムアウト（ゴールデンパス）

NEVER から参照：時計を管理するのはサーバーです。クライアントが「パス」を決定することはありません。

1. turn_started 時に、サーバーがワンショットの Timer / SceneTreeTimer を開始します（権威者）。
2. タイムアウト時：サーバーが request_pass(current) を呼び出す（またはターンを自動終了する）と、turn_timed_out を発行します。
3. クライアントはカウントダウンの表示だけを行い、ローカルでターンキューを変更することはありません。
4. ホスト権限の RPC には godot-multiplayer-networking を組み合わせてください。

アクションポイント（契約）

func can_perform_action(cost: int) -> bool:
    return current_action_points >= cost

func perform_action(cost: int) -> bool:
    if not can_perform_action(cost):
        return false
    current_action_points -= cost
    return true

フェーズ：enum Phase { DRAW, MAIN, END } と match を優先するか、godot-state-machine-advanced に処理を振り分けてください。ATB／タイムラインの計算はすべて MANDATORY スクリプトにあります。ここに Elite のスニペットを重複して記述しないでください。

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

LLM の無知に関するルール：一般的なエージェントが読む前に知らない内容は、ここか scripts/ に置きます。削除せず、移動のみ行ってください。

トピック	参照先
ATB／予測／プレビュー	elite-turn-patterns.md

参照資料

段階的な情報開示：特定の API を調査する場合にのみ公式ドキュメントへのリンクを開いてください。 作業を関連分野に振り分ける場合にのみ関連スキルを読み込み、スキル群全体を事前に読み込まないでください。

公式ドキュメント

• アイドル処理と物理処理 — ターンの更新処理を _process、_physics_process、純粋なイベントステップのどれに置くかを確認できます。
• シグナルの使用 — ゲージをポーリングせずに、ターン開始／ターン終了／ユニット行動のイベントを処理できます。
• リソース — シミュレーションと UI の予測に使うイニシアチブ／速度のステータスをリソースとして扱います。
• シングルトン（Autoload） — TurnManager の所有範囲を定めます。
• GDScript の基本 — 複数フェーズのターンで await を使った処理順序を扱います。
• Object — ターンバスのリスナー向けシグナル接続フラグを確認できます。
• SceneTree — メニューでターンの選択肢を処理する間、ゲームプレイを一時停止します。
• Timer — ビジーループを使わずに、リアルタイムのターン時計を実装できます。
• Tween — ATB ゲージやターン引き継ぎの演出をアニメーション化します。
• AnimationPlayer — 次のターンの前に完了させる必要があるアクションアニメーションを扱います。
• MultiplayerAPI — ネットワーク対戦で権威あるターン順を管理します。
• JSON — バランス調整用の環境で、決定論的なターンリプレイ／シードログを扱います。

関連スキル

前提条件

• godot-project-foundations — TurnManager のシーンと Autoload の配置。
• godot-signal-architecture — ターンバスの契約（シグナルは上方向、コマンドは下方向）。
• godot-resource-data-patterns — 戦闘／UI で共有する速度／イニシアチブのリソース。
• godot-autoload-architecture — グローバルなターンオーケストレーターのライフサイクル。

補完

• godot-state-machine-advanced — ターンフェーズの中にネストされたユニットごとの状態です。
• godot-combat-system — 付与されたターン中にアクションを解決します。
• godot-rpg-stats — 速度／AGI が ATB ゲージに反映されます。
• godot-ability-system — クールダウンを実時間だけでなく、ターン数で計測します。
• godot-tweening — ゲージの増加とターン引き継ぎの演出です。
• godot-multiplayer-networking — ホスト主導のターン順とロックステップです。

下流／利用側

• godot-genre-action-rpg — ARPG／JRPG系の戦闘における ATB／ターン制のハイブリッドです。
• godot-genre-card-game — カードのターンと優先権ウィンドウです。
• godot-genre-rts — ストラテジーのループにおける離散的な命令です。
• godot-monte-carlo-balancer — 速度／アクションの公平性を検証するため、ターンの組み合わせをシミュレーションします。

マスター

• godot-master — ライブラリのルーターであり、ターンシステム用のミラー化されたモジュールエントリーです。