godot-2d-animation

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

• AnimatedTextureは絶対に使用しないでください — このクラスは非推奨であり、最新のレンダラーでは非常に非効率です。また、将来のGodotバージョンで削除される可能性があります。代わりにAnimatedSprite2DまたはAnimationPlayerを使用してください。
• 複数のTweenで同じプロパティを操作しないでください — 複数のTweenで同じプロパティをアニメーションさせると、最後に作成されたものが強制的に優先されます。必ずTweenを変数に代入し、新しいものを作成する前に前のインスタンスでkill()を呼び出してください。
• 物理ティック以外でキネマティック移動を処理しないでください — AnimationPlayerでCharacterBody2Dを動かす場合は、AnimationPlayerのコールバックモードをPhysicsに設定してください。アイドル（レンダリング）フレーム中に物理ボディをアニメーションさせると、固定タイムステップの物理補間が崩れ、カクつきが発生します。
• ループアニメーションにanimation_finishedを使用しないでください — このシグナルはループしないアニメーションでのみ発火します。ループを検出するには、代わりにanimation_loopedを使用してください。
• play()を呼び出して即座に状態が変わると期待しないでください — AnimatedSprite2Dでは、play()の効果が次の処理フレームで適用されます。プロパティを同期的に更新する必要がある場合（たとえば、アニメーションの切り替えと同時にflip_hを変更する場合）は、play()の直後にadvance(0)を呼び出してください。
• アニメーションの進行状況を維持するときにframeを直接設定しないでください — frameを設定すると、frame_progressが0.0にリセットされます。フレーム途中でアニメーションを切り替える際に滑らかな遷移を維持するには、set_frame_and_progress(frame, progress)を使用してください。
• @onready var anim_spriteのキャッシュを忘れないでください — ノード検索のゲッターは、_physics_process()のような頻繁に実行される箇所では驚くほど遅くなります。必ず@onreadyを使用してください。
• AnimationPlayerのトラックと、コードで制御するAnimatedSprite2Dを混在させないでください — 各スプライトのアニメーション制御には、どちらか一方だけを使用してください。混在させるとちらつきや状態の競合が発生します。
• 変形に極端に薄いスケルトンを使用しないでください — 2Dメッシュには、バランスの取れた頂点密度が必要です。メッシュがうまく変形しない場合は、Mesh2Dエディターで関節付近の頂点数を増やしてください。

---

利用可能なスクリプト

必須：実装するパターンに対応するスクリプトを読んでください。これらのスクリプトと重複するインラインのレシピは削除されています。スクリプトが唯一の信頼できる情報源です。

読み込まないもの（シナリオ別）

シナリオ	読み込む	読み込まない
単一のキャラクター／プレイヤー	one_frame_sync_fix.gd、animation_state_sync.gd、必要に応じてanimation_tree_step.gd／tween_lifecycle_manager.gd	multimesh_swarm_anim.gd、gpu_mesh_optimizer.gd（フィルレートのプロファイリングで必要な場合を除く）
フレームイベント／ヒットボックス／SFXの同期	animation_sync.gd（およびAnimationPlayerのメソッドトラック）	Swarm／MultiMeshスクリプト
つぶし・伸ばしによるゲームフィール	必須 procedural_squash_stretch.gd	このスキル内の着地条件に関するインラインのスニペット
カットアウト／IKの四肢	skeleton_2d_rig_helper.gd	MultiMeshの群れ用スクリプト
アニメーション時のシェーダーフラッシュ／ディゾルブ	shader_hook.gd	—
数千匹のコウモリ／魚／小道具	multimesh_swarm_anim.gd（およびドキュメントの魚チュートリアル）	エンティティごとのAnimatedSprite2D／Tweenマネージャー

スクリプト一覧

• one_frame_sync_fix.gd — ゴールデン同期パス：play() + advance(0) と flip_h／プロパティの変更。
• animation_state_sync.gd — 状態駆動型アニメーション + トランジションキュー。
• animation_sync.gd — メソッドトラック、シグナルのオーケストレーション、ブレンドスペースのフック。
• animation_tree_step.gd — AnimationNodeStateMachinePlayback.travel()。
• procedural_squash_stretch.gd — 物理駆動のスクワッシュ／ストレッチの唯一の情報源（着地判定をここで再実装しないでください）。
• tween_lifecycle_manager.gd — Tween の破棄／再利用、プロパティ競合の防止。
• skeleton_2d_rig_helper.gd — FABRIK／CCDIK スタック、レストポーズ。
• shader_hook.gd — AnimationPlayer → ShaderMaterial の uniform。
• gpu_mesh_optimizer.gd — スプライト → フィルレート向けのタイトな 2D メッシュ。
• multimesh_swarm_anim.gd — GPU 群集モーション専用。
• animation_data_extractor.gd — 値／メソッドトラックで、ヒットボックス／スポーンのメタデータを SpriteFrames のビジュアルから分離します。
• procedural_walker_2d.gd — レイキャストターゲットによる TwoBoneIK の足の接地（skeleton_2d_rig_helper.gd と併用）。
• sprite_sheet_memory_manager.gd — VRAM の急増に対応する、高解像度フレームのスレッド経由での挿入とアンロード。

---

エキスパート向け判断ツリー：適切なアニメーションツールの選択

シナリオ	推奨ノード	エキスパートの見解
独立した、純粋なフレーム単位のスプライトシート	AnimatedSprite2D	ビジュアル以外のプロパティやメソッドトラックはアニメーション化できません。これらが必要になったら AnimationPlayer に切り替えてください。
カットアウトアニメーション、非ビジュアルの同期、オーディオ／パーティクル	AnimationPlayer	トランスフォーム、メッシュ変形、メソッド／値トラックを管理します。
複雑なステートマシン、ブレンド、移動	AnimationTree	AnimationPlayer 上のロジックグラフです。animation_tree_step.gd を介して travel() を使用してください。
プロシージャルで動的な、使い捨ての UI／エフェクト	Tween	実行時のターゲットです。必ず tween_lifecycle_manager.gd を経由してください。
数千のエンティティの群集	MultiMeshInstance2D + Shader	multimesh_swarm_anim.gd のみを読み込み、キャラクター同期スクリプトは使用しないでください。

---

ゴールデンパス：1 フレーム同期（play + advance(0)）

同じフレーム内でアニメーションとスプライトのプロパティを変更する場合、play() だけでは次のプロセスティックまで反映されず、1 フレームのグリッチが発生します。

必須：one_frame_sync_fix.gd を読んでください。最小限の契約：

# After any play() that must match flip/modulate/etc. this frame:
anim.flip_h = dir < 0
anim.play(&"run")
anim.advance(0)  # force pose now

関連項目：ループには animation_looped、単発再生には animation_finished を使用します。クリップの途中でスキンを切り替える場合は set_frame_and_progress を使用してください（AnimatedSprite2D のクラスドキュメントを参照）。

---

プロシージャルなスクワッシュ＆ストレッチ

着地処理のコードをエージェントに貼り付けないでください。以前の実装には、成立しない条件（not is_on_floor() and is_on_floor()）が含まれていました。

唯一の情報源として必須：procedural_squash_stretch.gd — 衝撃時のスクワッシュ、速度によるストレッチ、lerp による回復。床や速度の判定には godot-characterbody-2d／godot-2d-physics を併用してください。

---

クイックルーティング（レシピはスクリプトが管理します）

• Tween の割り込み／フラッシュループ → tween_lifecycle_manager.gd（1 つのプロパティに対して 2 つの Tween を競合させないでください）。
• AnimationTree の travel → animation_tree_step.gd（start の後に travel）。
• IK による足の接地 → skeleton_2d_rig_helper.gd + SkeletonModification2DTwoBoneIK のドキュメント。
• フィルレート／群集 → Do-NOT-Load テーブルに従って gpu_mesh_optimizer.gd／multimesh_swarm_anim.gd。
• ピクセルフィルター／共有 SpriteFrames → 公式ドキュメント（2D スプライトアニメーション、SpriteFrames）。preload を介してリソースを共有してください。

エキスパートの知見（WHY — 本文に記載）

• ハイブリッドなカットアウト＋セル — 体の動きにはボーンをアニメーションさせ、手や顔の切り替えには子スプライトの frame／texture をキーフレーム化します。理由：トランスフォームだけの動きは低コストで、セルの切り替えならリグを組み直さずにアートディレクションを維持できます。
• GPU フィルレート — 透明部分の大きいスプライトはフィルレートを無駄に消費します。理由：タイトな MeshInstance2D ポリゴンなら透明なテクセルをスキップできます。gpu_mesh_optimizer.gd と組み合わせてください。
• Tween のプロパティ競合 — 理由：同じプロパティを操作する最後の Tween が、何も通知せずに優先されます。前のインスタンスは必ず kill() してください（tween_lifecycle_manager.gd）。
• AnimationTree の travel — 理由：StateMachine は状態間の遷移に内部 A* を使用します。travel() の前に start() を呼び出してください（animation_tree_step.gd）。

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

トピック	リファレンス／スクリプト
シグナル／フレームイベント／スキンの切り替え	signals-and-frame-events.md
カットアウトリグ／プロシージャル IK による足の動き	cutout-and-skeletal.md
GPU メッシュ／群れ／メモリストリーミング	expert-techniques.md
フレームメタデータ／スポーンオフセット	animation_data_extractor.gd
非同期 SpriteFrames VRAM	sprite_sheet_memory_manager.gd

リファレンス

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

公式ドキュメント

• 2D スプライトアニメーション — フレームベースのシートとシグナルのタイミングに関する、AnimatedSprite2D と SpriteFrames の標準的なワークフローです。
• アニメーション機能の概要 — トラック、メソッド、非ビジュアルプロパティを扱うために、スプライトシートから AnimationPlayer に移行するタイミングを説明します。
• カットアウトアニメーション — 本格的なスケルトン IK に移行する前の、ペーパードールの階層構造とハイブリッドなカットアウト／セル構成について説明します。
• 2D スケルトン — カットアウトメッシュにおける Skeleton2D／Bone2D のリギング、レストポーズ、変形時の想定について説明します。
• AnimationTree の使用 — 基盤となる AnimationPlayer を駆動するブレンドスペースとステートマシングラフについて説明します。
• アニメーショントラックの種類 — フレーム単位で正確な SFX、ヒットボックス、シェーダーユニフォームのフックに使うメソッド／値／プロパティトラックについて説明します。
• AnimatedSprite2D — play()、advance()、set_frame_and_progress()、および animation_looped と animation_finished の仕様について説明します。
• SpriteFrames — AnimatedSprite2D が使用する共有フレームリソース、ループフラグ、アニメーションごとのタイミングについて説明します。
• Tween — AnimationPlayer のクリップを作成せずに実行時のスクワッシュ／ストレッチや、中断可能な単発の動きを実現する方法について説明します。
• 数千匹の魚をアニメーションさせる — ノードツリーから移行する必要がある群れの動きに向けた、GPU 頂点／MultiMesh のパターンについて説明します。
• SkeletonModification2DTwoBoneIK — Skeleton2D の構成で足や手をプロシージャルに接地させる、軽量な二関節 IK について説明します。

関連スキル

前提条件

• godot-animation-player — このスキルのハイブリッド／カットアウトのパターンで前提とする、AnimationPlayer の所有権、コールバックモード、トラックの作成方法について説明します。
• godot-characterbody-2d — アニメーションする CharacterBody2D の動きを固定タイムステップに合わせるための、物理ティックでの移動について説明します。
• godot-signal-architecture — ライフサイクルのリークを起こさずに animation_finished / animation_looped / frame_changed を安全に接続する方法について説明します。

補完

• godot-animation-tree-mastery — ここで扱う2D移動の基本を超えて、ブレンドツリー、OneShot レイヤー、travel() の経路探索を深く掘り下げます。
• godot-tweening — スカッシュ／ストレッチや UI のポップがインラインの create_tween() スニペットでは収まらなくなった場合に、Tween の合成方法を幅広く扱います。
• godot-shaders-basics — AnimationPlayer のトラックや MultiMesh 群のマテリアルで駆動する CanvasItem シェーダーのユニフォームについて説明します。
• godot-2d-physics — プロシージャル変形に影響する衝撃速度、IK ターゲット用のレイキャスト、補間ルールについて説明します。
• godot-state-machine-advanced — AnimationTree／AnimatedSprite2D が表示を担う一方で、ゲームプレイ FSM が意図を管理する設計について説明します。
• godot-particles — メソッドトラックやフレームイベントから生成する砂ぼこり、ヒットスパーク、軌跡について説明します。
• godot-adapt-3d-to-2d — 2D アニメーションノードを引き続き使用する、方向別シート、ビルボード、疑似奥行きソートについて説明します。

下流／利用者

• godot-genre-platformer — ジャンプ／着地／走行の表示スタックで、同期、スカッシュ／ストレッチ、ステートマシンの travel パターンを利用します。
• godot-genre-fighting — フレーム単位で正確なヒットボックスとメソッドトラックには、ここで扱う AnimationPlayer と AnimatedSprite2D の適切な使用方法が必要です。
• godot-resource-data-patterns — メモリ効率を保ちながら複数インスタンスのキャラクターに共有する .tres SpriteFrames とスキンパックについて説明します。

マスター

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