godot-ability-system

アーキテクチャ上の決定：マネージャーを配置する場所

スコープ	方針	スクリプト
キャラクター／敵／タレットごと	シーンスコープのマネージャーを子ノードとして配置（デフォルト）	エンティティ上の ability_manager.gd、またはコンポジション方式の ability_container.gd
シーン間で共有するアンロック／ロードアウトのカタログ	Autoload はカタログ／進行状況のみ（ランク、アンロックフラグ）を管理 — 実行中のキャスト状態は管理しません	軽量な Autoload データ。キャストは引き続きエンティティのマネージャーを介して実行します
「どこでも任意のアビリティをキャスト」するグローバル Autoload	避けてください	カプセル化とマルチプレイヤーの権限管理を損ないます

決定した方針： 実行中のクールダウン、GCD、execute() は、キャスター配下のシーンスコープの AbilityManager／AbilityContainer で処理します。Autoload にはアンロックランクを保存してもかまいませんが、戦闘中のキャスト判定元にしてはいけません。スキルツリー UI は進行状況データを読み書きし、その後キャスターのマネージャーを呼び出します — 戦闘中に /root/AbilityManager.use_* を呼び出してはいけません。

絶対に避けること

• _process() でクールダウン／ステータス効果の継続時間を更新しないでください — クールダウンをフレームスパイク時にも決定論的に保つため、_physics_process(delta) またはワンショット Timer を使用してください。
• 設計上、連続使用を防ぐ必要がある場合にグローバルクールダウン（GCD）を忘れないでください — 必要に応じて、キャスト間に短い共通ロック（0.5～1.5s）を設けます。
• マネージャーにアビリティ効果をハードコードしないでください — ストラテジーパターンを使い、各アビリティを execute() を持つ Resource／ノードにしてください（ability_resource.gd）。
• アニメーションロック中にキャストできるようにしないでください — is_casting／アニメーションシグナルで制御してください。
• 時間を正規化せずに残りクールダウン時間の浮動小数点値を保存しないでください — 絶対終了タイムスタンプ（Time.get_unix_time_from_system() + remaining）を永続化してください。
• 実行中の戦闘キャスト状態をグローバル Autoload に置かないでください — シーンスコープのマネージャーを使用してください（決定表を参照）。進行状況用の Autoload は問題ありません。
• オブジェクトプールを無条件に禁止したり、必須にしたりしないでください — GDScript の参照カウント方式では、軽量な VFX にプールは必須ではありません。弾丸／AoE の生成・破棄が高頻度の場合や、プロファイラーで割り当てがボトルネックとして確認された場合は、プールを使用してください。それ以外は、計測結果が出るまではインスタンス化／queue_free を優先してください。
• 深いアビリティ継承ツリーを作らないでください — Resource とコンテナを組み合わせてください（godot-composition）。

---

基本方針（必須）

1. ability_resource.gd — データと仮想 execute()
2. ability_manager.gd または ability_container.gd — シーンスコープのキャスト／クールダウン
3. buff_stat.gd — バフ／修正値がある場合
4. ダメージ解決 → godot-combat-system

シーンに AbilityManager／ComboSystem／SkillTreeManager の巨大な実装をインラインで貼り付けないでください。スキルツリーは進行状況 UI と前提条件グラフであり、キャスターのコンテナに Resource を付与します。

利用可能なスクリプト

• ability_resource.gd — 新しいアビリティを追加する前に必ず確認してください
• ability_manager.gd — 必須の Resource 駆動型クールダウンレジストリ（シーン単位）
• ability_container.gd — 必須の代替方式：アビリティごとのノード／Timer 構成
• buff_stat.gd — モジュール式バフステータス（バフがない場合は読み込まないでください）
• combo_tracker.gd — 時間枠付きコンボチェーン → フィニッシャーアビリティ
• charge_ability.gd — 複数チャージの再補充（Flash 方式）
• skill_node.gd / skill_tree_manager.gd — 前提条件グラフとポイント消費（進行システムのみ）
• status_effect.gd / status_effect_manager.gd — DoT／バフの定期処理（duplicate(true) が必要）
• ability_caster_network.gd — ローカルで予測し、authority が RPC シェルで検証します

クールダウンと状態のタイミングに関する契約

• クールダウンレジストリの更新とステータスの process_tick には、物理フレームの差分時間（_physics_process）またはコンテナが所有する Timer ノードを使用してください。
• アビリティによるヒット検出でインパルスやクエリを適用する場合は、物理ティック上で処理してください。
• UI は _process でクールダウンの進行状況を読み取ってもかまいませんが、正となる状態を管理してはいけません。

高度なテクニック（簡易版）

• 依存性注入： 親がキャスターのコンテキストを注入します。アビリティから get_node("/root/Player") を呼び出さないでください。
• ダックタイピングによるヒット処理： has_method(&"take_damage") または戦闘用 DamageData を使用してください。combat スキルを参照してください。
• 範囲攻撃： call_group または空間クエリを使用し、キャストのたびにツリー全体を走査しないでください。
• ネットワーク： ローカルで予測し、authority が can_use とコストを検証します（godot-multiplayer-networking）。
• スキルツリーのビジュアライザー： 設計時のグラフには @tool の GraphEdit を使用します。実行時には引き続き Resource をシーンマネージャーに付与します。

状態異常とコンボ（重要な理由）

CAUTION： 実行時に適用する状態異常／バフのテンプレートには、必ず duplicate(true) を使用してください。1 つの毒付き .tres を変更すると、そのアセットを共有するすべてのキャラクターに影響します。status_effect_manager.gd を参照してください。

• コンボ： combo_tracker.gd — 入力シーケンスの時間枠とレシピテーブルを使用します。フィニッシャーは通常の AbilityResource エントリのままです。
• チャージ： charge_ability.gd — 再補充のティックは UI の _process ではなく、_physics_process に設定してください。
• スキルツリー： skill_tree_manager.gd はアビリティをキャスターのシーンマネージャーに付与します。進行システム用の Autoload が保持するのはランクのみです。
• クールダウンの保存： 残り時間の生の浮動小数点値ではなく、絶対終了タイムスタンプ（Time.get_unix_time_from_system() + remaining）を保存してください。これにより、時計や読み込みを悪用した不正を防げます。

上記の箇条書きの範囲を超えるコンボ／チャージ／スキルツリー／状態異常／ネットワーク処理の詳細には、elite-ability-patterns.md が必須です。最初の AbilityResource + AbilityManager の実装では読み込まないでください。

参考資料

段階的な情報開示： 実装する API（Resources、タイマー、シグナル、保存、マルチプレイヤー）についてのみ、公式ドキュメントをざっと確認してください。関連システムを接続する際は関連スキルを開き、スキル群全体を事前に読み込まないでください。

公式ドキュメント

• リソース — アビリティの定義、バフ、状態異常は、ハードコードされたマネージャーの切り替え処理ではなく、Resource データとして扱います。これにより、デザイナーがアセットを作成し、共有できます。
• Resource — 実行時に状態異常やバフのテンプレートを適用する際は、duplicate(true) を使います。そうすれば、あるキャラクターの時間経過による状態変化が、全員で共有する .tres を変更することはありません。
• GDScript のエクスポート — @export / @export_group を使うと、アビリティの Resource 上でコスト、クールダウン、前提条件、効果の配列を Inspector から調整できます。
• シグナルの使用 — ability_cast、ability_ready、クールダウンのライフサイクルシグナルを発行すると、UI や VFX は AbilityManager の内部実装と結合せずに購読できます。
• シーンの構成 — 「シグナルは上へ、呼び出しは下へ」を徹底します。親ノードや UI がシグナルを受け取り、マネージャーは戦闘状態をグローバルに参照するのではなく、アビリティの Resource やノードを呼び出します。
• アイドル処理と物理処理 — クールダウンと GCD は固定デルタの _physics_process で更新します。フレームの急増で同期がずれるクールダウン計算に _process を使うのは避けてください。
• Timer — ワンショットの Timer 子ノードを使う方法は、コンテナ形式のマネージャーでアビリティごとのクールダウンを管理する、すっきりとした構成パターンです。
• SceneTreeTimer — create_timer() / await のパターンは、詠唱時間や短時間のバフに適しています。詠唱ごとに永続的な Timer ノードを追加する必要はありません。
• グループ — 範囲攻撃のアビリティでは、ヒット対象を毎回手作業でシーンから探すのではなく、call_group（またはグループのクエリ）を使います。
• Time — セーブ／ロードをまたいでクールダウンを保持するには、残り時間の浮動小数点値ではなく、クールダウンの終了時刻（get_unix_time_from_system() ＋ 残り時間）を保存します。
• ゲームの保存 — アビリティのアンロックランクと絶対的なクールダウン終了時刻は、プレイヤーの進行状況データと一緒にシリアライズします。
• ハイレベルマルチプレイヤー — 権威サーバーによる詠唱の検証と、@rpc による確定／キャンセルが、予測アビリティ詠唱におけるエンジンの基本パターンです。

関連スキル

前提条件

• godot-resource-data-patterns — アビリティ、バフ、スキルツリーのノードは Resource を第一に考えます。アビリティデータ用に独自のシリアライズ方式や継承ツリーを考案する前に、こちらを読みます。
• godot-signal-architecture — 詠唱、準備完了、クールダウンのシグナルと UI の連携には、AbilityManager がキャラクターや HUD から独立した状態を保てるよう、規律あるシグナルの所有権が必要です。
• godot-composition — 実行時の振る舞いには、BaseAbility → MagicAbility → FireAbility のような深い継承より、AbilityContainer やコンポーネントノードを優先します。
• godot-gdscript-mastery — 仮想の execute() / can_cast()、型付き Resource、タイマーを待機する詠唱フローを使うには、GDScript の確かなパターンを理解している必要があります。

補完

• godot-combat-system — ダメージ、被弾リアクション、ターゲティングのパイプラインでは、能力の execute() の結果を使用します。DamageData は能力のメタデータと分けてください。
• godot-rpg-stats — マナ／スタミナのコスト、スキルランクによるステータスボーナス、バフ倍率には、一貫したステータス／修正値レイヤーが必要です。
• godot-input-handling — ホットバー／アクションマップの入力からは、入力コールバックにクールダウン処理を埋め込むのではなく、can_use／use_ability を呼び出してください。
• godot-animation-player — アニメーションロックと詠唱予告で能力の連続使用を制御します。AnimationPlayer の開始／終了を is_casting に接続してください。
• godot-state-machine-advanced — 詠唱、チャネリング、中断の状態は、アビリティマネージャーに問い合わせるキャラクターのステートマシンに含めます。逆にしてはいけません。
• godot-save-load-systems — スキルランク、アンロックフラグ、絶対クールダウン終了時刻は、プロジェクトのセーブスキーマを通じて往復できるようにする必要があります。

下流／利用側

• godot-monte-carlo-balancer — クールダウン、コスト、ダメージ／効果の Resource を調整可能にした後、モンテカルロによるロードアウトシミュレーションで、リリース前に能力の DPS／稼働率の範囲を検証します。
• godot-multiplayer-networking — キャストの予測、権限チェック、失敗した RPC のロールバックは、アビリティマネージャーの can_use と execute の分離を基盤とします。
• godot-genre-action-rpg — アクション RPG のスキルバー、スキルツリー、能力連携では、このスキルを戦闘、ステータス、進行要素と組み合わせます。
• godot-inventory-system — 消耗品の巻物、スキルブック、能力を付与する装備によって、インベントリからの付与を AbilityManager の登録につなげます。

マスター

• godot-master — ライブラリのルーターであり、対応するモジュールのエントリです。関連スキルの確認や、ドメインスキルの編集後に共有スクリプトのミラーを同期するときに使用します。