godot-animation-tree-mastery

AnimationTree の習得

Godot の高度なアニメーションブレンドとステートマシンに関する専門的なガイダンスです。

絶対にしないこと

• AnimationTree を使用しているときに、AnimationPlayer で play() を絶対に呼び出さないでください — AnimationTree がプレイヤーを制御します。play() を直接呼び出すと競合やカクつきが発生します。代わりに set("parameters/transition_request") または travel() を使用してください。
• active = true の設定を絶対に忘れないでください — AnimationTree はデフォルトで非アクティブです。$AnimationTree.active = true にするまでアニメーションは再生されません。
• パラメーターへのアクセスに絶対パスを使用しないでください — "parameters/StateMachine/transition_request" のような相対パスを使用してください。これにより、ノードを階層内で移動しても互換性が保たれます。
• インタラクティブな状態で auto_advance を有効にしたままにしないでください — 即座に遷移してしまいます。コンボチェーンや死亡からリスポーンへの遷移など、自動化されたシーケンスでのみ使用してください。
• 1D ブレンドに BlendSpace2D を使用しないでください — 速度だけをブレンドする場合は BlendSpace1D を使用してください。2 つの状態だけをブレンドする場合は Blend2 を使用してください。BlendSpace2D は X+Y の方向入力（ストレイフ）専用です。
• ガードなしで毎フレーム AnimationTree のパラメーターを更新しないでください — 変更がない場合でも毎フレーム set() でパラメーターを設定すると、キャッシュが無効化され、カクつきが発生する可能性があります。まず値が同じか確認してください。
• 単純なロジックに深くネストした BlendTrees を使用しないでください — レイヤーを重ねるたびに CPU 負荷が増えます。StateMachine またはスクリプトで制御するシンプルな Blend2 で処理できるロジックは、そちらで処理してください。
• パラメーターを同期的に更新するときに、await get_tree().process_frame の処理を忘れないでください — 次のパラメーター変更を反映する前に、ツリーが状態を調整するためのフレームが 1 つ必要になることがあります。
• 長いカットシーンで auto_advance に頼らないでください — アニメーションが中断されると、auto_advance によってキャラクターの状態が破綻する可能性があります。代わりに Method Tracks を使用して状態の完了を通知してください。
• 再生時間が大きく異なるアニメーションに Sync グループを使用しないでください — 片方のアニメーションが極端な速度で再生されることになります。長さの合わないサイクルには TimeScale または別々のレイヤーを使用してください。

---

利用可能なスクリプト

必須：対応するパターンを実装する前に、適切なスクリプトを読んでください。 読み込まないでください。ネストされた戦闘グラフ、IK のルックアット、または深い BlendTree レイヤーが対象に含まれない限り、references/advanced-graph-recipes.md は読み込まないでください。

sync_parameter_manager.gd

ガード付きの AnimationTree パラメーター書き込み — 物理フレームごとの冗長な set() 呼び出しを防ぎます。

statemachine_travel_code.gd

travel() / start() による AnimationNodeStateMachinePlayback のプログラム制御。

tree_travel_manager.gd

条件：複数のマシン間の遷移／リクエストキュー。 AnimationPlayer.play() を呼び出さずに、ネストされた再生パス全体の遷移リクエストを一元管理します。

nested_state_machine.gd

条件：移動＋戦闘（または空中）のサブマシン。 ネストされた StateMachine のパラメーターパスと再生の引き継ぎを扱います。

skeleton_ik_lookat.gd

条件：ツリーの横にエイム／ルックアットを追加する場合。 ツリーが所有するボーントラックと競合させずに LookAtModifier3D／IK を使用します。

reactive_oneshot_vfx.gd

反動、まばたき、被弾リアクションに AnimationNodeOneShot を使用します。

dynamic_timescale_control.gd

バレットタイムやヘイストの倍率に対応した、実行時の再生速度制御。

advanced_transition_masking.gd

上半身と下半身を分離するための Add2／Blend2 のボーンフィルターマスク。

blendtree_logic_mixing.gd

BlendTree グラフ内でインタラクティブな戦闘レイヤーをミックスします。

root_motion_animtree_sync.gd

AnimationTree のルートモーションから CharacterBody の移動を抽出します。

sync_group_layering.gd

長さが同じ複数レイヤーのクリップ（例：歩行＋リロード）用の同期グループです。

nested_tree_architecture.gd

階層型ステートマシン／ネストしたパラメーターパスのアーキテクチャです。

runtime_tree_debugging.gd

実行時に現在の状態、遷移経路、ブレンド値を可視化します。

animation_event_dispatcher.gd

メソッドトラック → dispatch_event(name, metadata) のシグナルブリッジです。VFX／オーディオをグラフコードから分離します。

animation_complexity_manager.gd

VisibleOnScreenNotifier3D が画面外のアクターをカリングするときに、ヒーロー用と群衆用の tree_root グラフを切り替えます。

---

決定木（インラインチュートリアルの置き換え）

必要なこと	推奨	スクリプト
シンプルなクリップ切り替え／UI／小道具	AnimationPlayer のみ	Peer godot-animation-player
ゲームプレイの状態が5つ以上、遷移あり	StateMachine ルート	statemachine_travel_code.gd, tree_travel_manager.gd
速度のみのブレンド	BlendSpace1D	sync_parameter_manager.gd を介したガード付き書き込み
ストレイフ／照準 X+Y	BlendSpace2D	同上＋blend_position
上半身のオーバーレイ／戦闘レイヤー	BlendTree Add2/Blend2/OneShot	blendtree_logic_mixing.gd, reactive_oneshot_vfx.gd
ロコモーション内にネストした戦闘／空中状態	Nested SM	必須 nested_state_machine.gd
注視／IK	ツリーの隣に置くモディファイア	必須 skeleton_ik_lookat.gd
詳細なグラフレシピ	references/	必要な場合を除き読み込まないでください → advanced-graph-recipes.md

コアコンセプト（簡潔版）： AnimationTree は anim_player を介して AnimationPlayer を所有します。ルートは StateMachine／BlendTree／BlendSpace です。パラメーターには相対 "parameters/..." パスを使用します。_ready で active = true を一度設定します。

@onready var anim_tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = anim_tree.get("parameters/StateMachine/playback")

func _ready() -> void:
    anim_tree.active = true

StateMachine／BlendSpace エディターの手順をそのまま全文貼り付けないでください。AnimationTree エディターでグラフを作成し、上記のスクリプトで制御します。

---

エキスパートの知見（理由 — 本文に残す）

• Advance 条件と travel の違い — 理由：bool 条件は遷移を自動で実行しますが、travel() は明示的な経路指定です。ダメージ／死亡イベントには条件を、ロコモーションの意図には travel を使用してください。
• BlendSpace2D のコスト — 理由：8方向ブレンドでは複数のクリップをサンプリングします。速度のみの場合は BlendSpace1D を、2状態間のクロスフェードには Blend2 を使用してください。
• パラメーターガード — 理由：冗長な set() はフレームごとにツリーのキャッシュを無効化します。sync_parameter_manager.gd を介して書き込みを行ってください。
• メソッドトラック — 理由：ゲームプレイ側では、アニメーション名を解析せずにディスパッチャーのシグナルを監視してください。animation_event_dispatcher.gd を参照してください。

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

トピック	リファレンス／スクリプト
StateMachine／BlendSpace エディターのレシピ	statemachine-and-blendspace.md
ネストした戦闘／IK／ルートモーション	advanced-graph-recipes.md

リファレンス

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

公式ドキュメント

• AnimationTree の使用 — play() を自分で呼び出すことなく AnimationPlayer を制御する、BlendTree／StateMachine／BlendSpace グラフの標準的なワークフローです。
• アニメーション機能の概要 — ブレンド、トラベル、レイヤー化された表現に AnimationTree を使うために、AnimationPlayer だけで扱うクリップから移行するタイミングを説明します。
• アニメーショントラックの種類 — ツリーがすでにブレンドしているクリップからゲームプレイイベント（足音、ヒットボックス）を発生させるメソッドトラックと値トラックです。
• AnimationTree — このスキル全体で使用する active、tree_root、anim_player、ルートモーションのゲッター、および parameters/* のパス規約について説明します。
• AnimationNodeStateMachine — コードから travel() を呼び出す前に、ネストされた移動／戦闘グラフを作成し、遷移を設定する方法を説明します。
• AnimationNodeStateMachinePlayback — 実行時の travel()、start()、get_current_node()、およびコード駆動の状態変更に使うトラベルパスの確認について説明します。
• AnimationNodeStateMachineTransition — 遷移が固定されたり、意図せず即時に実行されたりするのを防ぐ、進行条件、auto_advance、Sync、クロスフェード、優先順位のルールについて説明します。
• AnimationNodeBlendSpace2D — blend_position による方向別のストレイフ／照準ブレンドについて説明します（速度のみが必要な場合は BlendSpace1D を使用してください）。
• AnimationNodeBlendTree — 上半身の照準、戦闘オーバーレイ、フィルターマスクに使う、レイヤー化された Add2／Blend2／OneShot グラフについて説明します。
• AnimationNodeOneShot — 反動、被弾リアクション、その他の優先度が高い非ループ型オーバーレイに使う FIRE／ABORT リクエストの列挙型について説明します。
• AnimationNodeTimeScale — Engine.time_scale を変更せずに、加速、スタン、バレットタイムに合わせてサブツリーごとに再生速度を設定できます。
• LookAtModifier3D — ツリーと並行して動作するスケルトンのルックアット機能です。relative のデフォルト値の変更については、migration-notes.md を参照してください。

関連スキル

前提条件

• godot-animation-player — AnimationTree は AnimationPlayer で作成したクリップの再生を管理します。ブレンドする前に、トラックの構成と所有関係が正しく設定されている必要があります。
• godot-input-handling — 各物理フレームで blend_position、進行条件、トラベル先に渡すスティック／キーボードのベクトルとアクションについて説明します。
• godot-signal-architecture — ライフサイクルのリークを防ぐ、メソッドトラックのディスパッチャーとアニメーション完了系シグナルの安全な接続方法を説明します。

補完

• godot-2d-animation — AnimationTree BlendSpaces またはシンプルな遷移グラフを引き続き使用する、シート／カットアウトアニメーションと2D移動の表現です。
• godot-state-machine-advanced — ゲームプレイ FSM が意図を管理し、AnimationTree が表現上の遷移とブレンドを管理する構成です。
• godot-physics-3d — AnimationTree のルートモーション抽出に対応する CharacterBody3D / move_and_slide の統合です。
• godot-characterbody-2d — StateMachine の遷移と BlendSpace の位置を駆動する、固定タイムステップの2D移動入力です。
• godot-tweening — バレットタイムと戦闘のブレンド量のランプを中断可能にするための、TimeScale またはブレンド量のトゥイーン処理です。
• godot-combat-system — OneShot リクエスト、上半身の Add2 マスク、ネストされた戦闘サブマシンを利用する、ヒットリアクション／コンボレイヤーです。
• godot-debugging-profiling — 遷移経路、ブレンド値、画面外の active カリングを検証する際の、プロファイリングとロギングの原則です。

下流／利用者

• godot-genre-action-rpg — これらのグラフパターンを基にした、移動＋戦闘スタンスのツリーと、アビリティ発動用の OneShot です。
• godot-genre-fighting — フレームに依存するコンボの自動進行とマスクされた上半身攻撃は、ここでの遷移と BlendTree の適切な管理に依存します。
• godot-genre-shooter-fps — 移動の BlendSpaces に重ねる、照準／リロードのオーバーレイ、反動の OneShot、注視点修飾子です。

マスター

• godot-master — スキルを横断して見つけるための、ライブラリルーター兼ミラー化されたモジュールエントリです。