godot-animation-player

AnimationPlayer

タイムラインベースのキーフレームアニメーション：トラックの選択、RESET、ルートモーション、ライブラリ — レシピはスクリプトで管理します。

絶対にしてはいけないこと

• RESET トラックを絶対に忘れないでください — 忘れると、シーン切り替え後もアニメーション対象のプロパティがそのまま残ります。
• ワンショットのロジックに Animation.CALL_MODE_CONTINUOUS を絶対に使わないでください — CALL_MODE_DISCRETE を使います。
• 埋め込みリソースのプロパティを直接アニメーションさせないでください — インスタンスごとのユニフォームや所有するマテリアルを優先します。
• ループするクリップに animation_finished を絶対に使わないでください — animation_looped を使うか、current_animation をポーリングします。
• 大規模なコードでアニメーション名の文字列を絶対にハードコードしないでください — 定数または StringName を使います。
• 同一フレーム内での読み取りが重要なとき、update=true を指定せずに seek() を絶対に呼び出さないでください。
• 画面外で視覚効果のみに使うプレーヤーを、絶対に active のままにしないでください — Notifier でカリングします。
• 再生中の AnimationLibrary を絶対に変更しないでください — 先に停止するか、再生終了を待ちます。
• 長時間の同期に speed_scale を絶対に頼らないでください — 共有クロックに対する seek() を優先します。

---

使用可能なスクリプト（必須のトリガー）

該当するパターンを実装する前に、対応するスクリプトを開いてください。詳しいレシピ：track-authoring.md、root-motion-and-sequences.md、edge-cases.md。

必要な内容	スクリプト
メソッドトラックのヒット／状態キー	method_track_logic.gd
スタンス／武器ライブラリの切り替え	runtime_anim_lib_swapper.gd
シェーダーユニフォームのタイムライン	dynamic_shader_animation.gd
実行時のトラック調整	procedural_track_modifier.gd
RESET の強制オーケストレーション	reset_track_orchestrator.gd
ベジェ → プロシージャル駆動	bezier_curve_extraction.gd
画面外での active カリング	active_animation_culler.gd
ルートモーションと物理演算の同期	root_motion_physics_sync.gd
パーツ／装備トラック	character_part_swapper_tracks.gd
TYPE_AUDIO の足音同期	precise_audio_sync.gd
キュー／分岐シーケンス	animation_sequencer.gd
コードで構築する Animation リソース	programmatic_anim.gd
代替のオーディオトラック設定に関するメモ	audio_sync_tracks.gd

重要な理由（本文に残すこと）

• CALL_MODE_CONTINUOUS はキーの範囲内で毎フレームメソッドを呼び出します — ワンショットの当たり判定／VFX には CALL_MODE_DISCRETE が必要です。
• 埋め込みのサブリソースプロパティ（例：material.albedo_color）をアニメーションさせると、リソースがシーンに複製されます — インスタンス化したマテリアルや shader_parameter/* トラックを使います。
• ループするクリップでは animation_finished は発火しません — animation_looped を使うか、current_animation をポーリングします。
• 再生中の AnimationLibrary を変更するとクラッシュしたり、トランスフォームが不正になったりします — 切り替える前に停止するか、再生終了を待ちます。
• speed_scale はリズム／マルチプレイヤーでずれが生じます — 長時間の同期には、共有クロックを使った seek(t, true) を使います。

トラック選択マトリクス

トラック	使用する場合	避ける場合
Value	プロパティ（位置、modulate、ユニフォーム）のアニメーション	実行時に一度だけ加える演出 → Tween
Method	タイムスタンプでの当たり判定、SFX フック、状態切り替え	CONTINUOUS 呼び出しモード／パス上にメソッドがない場合
Audio	フレームに同期した足音／VO	AudioStreamPlayer.play() のタイミングずれを許容できる場合
Bezier	実行時にサンプリングするカスタムイージングカーブ	単純な線形フェード

トラック作成のサンプル → track-authoring.md。

ルートモーション（物理演算）

CharacterBody3D + Skeleton3D + AnimationPlayer：物理ティックで get_root_motion_position()／回転を使って抽出します — root_motion_physics_sync.gd。ボーンだけを動かす歩行サイクルでは、ボディのコライダーがその場に残ります。

シーケンス、ブレンド、RESET

• チェーン再生：animation_set_next / queue / animation_sequencer.gd。
• 歩き↔走りの見た目を滑らかにするブレンド時間には、play("run", -1, 1.0, 0.5) または set_default_blend_time を使用します。
• デフォルト値を設定した RESET クリップを必ず作成してください。編集時には「保存時にリセット」を有効にします。
• 逆再生：ドアやシネマティックの巻き戻しには、play("clip", -1, -1.0) を使用します。

詳しい手順 → root-motion-and-sequences.md。

AnimationPlayer と Tween の比較

必要なもの	推奨
タイムライン／多数のプロパティ／再利用可能	AnimationPlayer
実行時の単発処理／割り込み可能	Tween（godot-tweening）

エキスパート向けアーキテクチャ（スクリプト）

パターン	スクリプト	理由
人型キャラクター用の共有ライブラリ	runtime_anim_lib_swapper.gd	1 つのライブラリを多数のモデルで使用できます — lib/clip を再生
タイムラインイベントの分離	method_track_logic.gd	メソッドトラック → シグナル発信側 → ゲームプレイのリスナー
画面外の CPU 予算	active_animation_culler.gd	active = false または手動で advance() を実行
コードで作成するクリップ	programmatic_anim.gd	FBX に存在しない動的なターゲット

リファレンス

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

公式ドキュメント

• アニメーション機能の概要 — AnimationPlayer が Tween やスプライトではなくタイムラインを管理する場合や、ライブラリ、RESET、エディターがどのように連携するかを解説します。
• アニメーショントラックの種類 — このスキルのパターンで必要となる、値、メソッド、ベジェ、オーディオの各トラックと、呼び出しモードやキー設定のルールを解説します。
• AnimationPlayer — play／queue／seek、ブレンド時間、animation_finished と animation_looped の違い、active によるカリングを解説します。
• Animation — トラック API（track_insert_key、呼び出しモード、オーディオ／ベジェのヘルパー）と、長さ／ループのメタデータを解説します。
• AnimationLibrary — モデルごとにトラックを複製することなく、add_animation_library で共有のスタンス／武器用クリップ集を追加する方法を解説します。
• AnimationMixer — 物理同期や予算管理で使用する、ルートモーションのゲッター、コールバックの処理モード、advance() を解説します。
• AnimationTree の使用 — 手動で queue を使う代わりに、ブレンド／ステートマシンで基盤となる AnimationPlayer を制御すべき状況を解説します。
• Tween — AnimationPlayer と Tween の選択基準において、実行時の単発モーションに対応する選択肢です。
• アニメーションの追加（初めての 3D ゲーム） — 高度なトラック作成に進む前に、インポートから AnimationPlayer の再生ループまでを実践的に解説します。
• VisibleOnScreenNotifier3D — 画面外の CPU 使用量を削減するため、画面への出入りのシグナルを使って AnimationPlayer.active を切り替える方法を解説します。

関連スキル

前提条件

• godot-signal-architecture — ライフサイクルリークを起こさずに、animation_finished／animation_looped／カスタムメソッドトラックを安全にシグナル接続します。
• godot-resource-data-patterns — 共有 .tres AnimationLibrary の所有権を管理し、実行時の差し替えによって再生中のリソースが重複したり、安全でない形で変更されたりするのを防ぎます。
• godot-gdscript-mastery — 型付きのトラック生成、パス文字列、Dictionary のメソッドトラックペイロードを扱います。

補完

• godot-animation-tree-mastery — ロコモーションが AnimationPlayer の queue／set_next では対応しきれなくなった場合に、ブレンドツリー、OneShot レイヤー、travel() を使います。
• godot-2d-animation — AnimationPlayer のメソッドトラックとプロパティトラックに引き続き依存する、AnimatedSprite2D／Skeleton2D の表示を扱います。
• godot-tweening — 完全な Animation リソースを作成するのが過剰な場合に、中断可能な実行時トゥイーンを使います。
• godot-shaders-basics — マテリアルを埋め込まずに、値トラック（shader_parameter/*）で ShaderMaterial のユニフォームを駆動します。
• godot-audio-systems — TYPE_AUDIO トラックを中心としたバス／ボイスのプーリングと、タイムライン上での足音／SFX のタイミングを扱います。
• godot-physics-3d — 物理ティックでルートモーションの位置／回転を抽出するために、CharacterBody3D と統合します。

下流／利用側

• godot-genre-fighting — フレーム単位で正確なヒットボックスの有効時間と、キャンセル可能時間の離散メソッドトラックを扱います。
• godot-genre-platformer — 2D／3D の移動体におけるジャンプ／着地／走行クリップ、RESET の適切な管理、ブレンド時間を扱います。
• godot-combat-system — AnimationPlayer のメソッドトラックからダメージ／VFX イベントを発行する攻撃タイムラインを扱います。

マスター

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