godot-tweening

判断ツリー — Tween と AnimationPlayer の使い分け

状況	選択
一度限りの UI の演出、ホバー、ポップアップ、スコアカウント、反動	Tween（create_tween）
作成済みの複数トラックのクリップ、スクラブ可能なタイムライン、ブレンドツリー	AnimationPlayer / AnimationTree
移動するターゲットをカメラが継続的に追従	Camera2D.position_smoothing / スプリング追従 — _process のたびに新しい Tween を作成する方法は使わないでください
Engine.time_scale == 0 中のメニューアニメーション	set_ignore_time_scale(true) を設定した Tween — 必須 time_scale_ignored_ui.gd
再トリガー可能なプロパティ（ボタンの連打、回避のキャンセル）	再作成前に破棄 — 必須 safe_tween_interruption.gd
物理ボディ / ネットワーク補正の動き	TWEEN_PROCESS_PHYSICS + reset_physics_interpolation

利用可能なスクリプト

必須：Tween の処理を書く前に、該当するケースのスクリプトを読んでください。

safe_tween_interruption.gd

再トリガー可能な Tween では必須です。新しい Tween を開始する前に、アクティブな Tween を破棄してください。

time_scale_ignored_ui.gd

ポーズメニュー / time_scale == 0 中の UI アニメーションでは必須です。

nested_subtween_cutscene.gd

tween_subtween による合成可能なカットシーンのタイムラインでは必須です。

parallel_popup_animation.gd

複数プロパティの UI トランジションには、set_parallel(true) + chain() を使用します。

text_counter_method_tween.gd

プロパティではない値（スコア文字列）には tween_method を使用します。

custom_curve_tween.gd

独自のイージングには Curve リソースを使用します。

camera_shake_tween_logic.gd

ループする Tween を使った手続き型の画面シェイクです（追従ではなく、オフセットを使用）。

relative_recoil_tween.gd

反動の微調整には as_relative() / from_current() を使用します。

staggered_inventory_entry.gd

1 つの Tween で、コレクション項目を順番に表示します。

looped_hover_vfx.gd

無限に往復する環境演出です。

juice_manager.gd / tween_builder.gd

多くのシステムで演出プリセットを共有する場合に使う、演出の一元的な振り分け / ビルダーヘルパーです。

Tween を使う際に絶対にしてはいけないこと

• Tween.new() で Tween をインスタンス化しないでください — 必ず create_tween() または get_tree().create_tween() を使用してください [3, 4]。
• 完了した Tween を再利用しないでください — Tween は一度しか使えません。再生するには作り直してください [4]。
• PropertyTweener または CallbackTweener を手動でインスタンス化しないでください — 親 Tween のメソッド経由でのみ使用してください [5]。
• 0 秒のアニメーションだけを含む無限ループを作成しないでください — エンジンがフリーズします [10]。
• 同じプロパティを複数の Tween で同時にアニメーションさせないでください — 先に古い参照を kill() してください [11, 12]。
• UI / 演出に線形補間を使用しないでください — EASE_OUT + TRANS_QUAD または EASE_IN_OUT + TRANS_CUBIC を推奨します [22]。
• ガードなしで _process 内に Tween を作成しないでください — 毎秒 60 個の Tween を作成すると、アプリがクラッシュします。
• グローバルではない Tween で bind_node(self) を省略しないでください — バインドすると、ノードとともに Tween も破棄されます [13]。
• 状態変更に 0 秒の Tween を使用しないでください — プロパティを直接設定してください [20]。
• set_parallel(true) から戻るときに chain() を呼び忘れないでください [15]。

---

ライフサイクルの基本パターン

var _tween: Tween

func animate_to(pos: Vector2) -> void:
    if _tween and _tween.is_valid():
        _tween.kill()
    _tween = create_tween().bind_node(self)
    _tween.set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_QUAD)
    _tween.tween_property(self, "position", pos, 0.35)

必須のパターンの参照元： safe_tween_interruption.gd。

カメラ追従（正しい方法）

継続的な追従は Tween の用途ではありません。

extends Camera2D
@export var target: Node2D

func _ready() -> void:
    position_smoothing_enabled = true
    position_smoothing_speed = 5.0

func _physics_process(_delta: float) -> void:
    if target:
        global_position = target.global_position

一度限りのカメラのパンチや戻りを Tween で行う必要がある場合は、Tween の参照を1 つだけ保持し、再作成前に破棄してください。ガードのない _process 内で create_tween() を呼び出すことは絶対に避けてください。

エキスパート向けパターン（維持）

物理同期 Tween アニメーション

func apply_physics_tween(target: Node3D, start_pos: Vector3, goal: Vector3) -> void:
    target.global_position = start_pos
    target.reset_physics_interpolation()
    var tween := create_tween().bind_node(target)
    tween.set_process_mode(Tween.TWEEN_PROCESS_PHYSICS)
    tween.tween_property(target, "global_position", goal, 0.5)

演出設定リソース

演出の duration/trans/ease を Resource に保存し（演出スクリプトを参照）、演出をデータ駆動にします。

Tween-Event-Sequencing

並列ブロック → chain() → インターバル／コールバック → 終了。ネストされたモジュールには、nested_subtween_cutscene.gd を推奨します。

Bezier-Path-Tween

独自にベジェ計算を実装する代わりに、PathFollow2D.progress_ratio をトゥイーンします。

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

LLM の無知ルール：一般的なエージェントが読む前に知らない情報は、ここまたは scripts/ に置きます。削除せず、移動してください。

トピック	リファレンス
チェーン、kill、注意点	tween-recipes-and-gotchas.md

リファレンス

段階的開示：特定の API を調べるときにのみ「公式ドキュメント」のリンクを開き、関連スキルは隣接する領域へ案内するときに読み込みます。関連スキル全体をあらかじめ読み込まないでください。

公式ドキュメント

• Tween — create_tween、parallel／chain、ループ、処理モード、ignore_time_scale、kill／ライフサイクルのルール。
• PropertyTweener — tween_property の詳細：as_relative、from_current、カスタム補間器、ステップごとの ease／trans。
• MethodTweener — プロパティ以外の値（スコアカウンター、シェーダーパラメーター、Curve でサンプリングした動き）に対する tween_method。
• CallbackTweener — 0 秒のプロパティステップを無理に作ることなく、順序付きの副作用を実行する tween_callback。
• IntervalTweener — 単一の Tween タイムライン内で遅延させる tween_interval。
• SubtweenTweener — 1 つの親タイムライン内にネストしたカットシーンモジュールを配置する tween_subtween。
• 補間 — イージングの選択とカスタム補間器の基礎となる lerp／smoothstep。
• ベジェ、曲線、パス — プロパティのトゥイーンだけではパスを表現できない場合に使う Curve／PathFollow のパターン。
• アニメーション機能の概要 — Tween で十分な場合と、AnimationPlayer／AnimationTree でトラックを作成する場合。
• SceneTree の使用 — bind_node だけでは不十分な場合の SceneTree.create_tween とノードのライフタイム。
• アイドル処理と物理処理 — TWEEN_PROCESS_PHYSICS の同期に使うアイドル／物理処理モード。
• 物理補間クイックスタートガイド — 補間対象のボディでトランスフォームをトゥイーンする場合の reset_physics_interpolation。

関連スキル

前提条件

• godot-project-foundations — create_tween／bind_node のライフサイクルパターンを学ぶ前に、シーンツリー、Node の所有権、リソースの基礎を確認します。
• godot-gdscript-mastery — tween_method と finished ハンドラーで使う、型付き callable、ラムダ、await／シグナルの慣用句を学びます。

補完

• godot-2d-animation — Tween の演出と併用されることの多いスプライト／スケルトンのモーションと、共有する kill／ライフサイクル管理の規律を扱います。
• godot-animation-player — 複雑なタイムラインには作成済みのクリップを使い、実行時／プロシージャルな UI や単発の演出には Tween を使います。
• godot-ui-containers — ポップアップの拡大・フェードや、インベントリの項目を段階的に表示する Tween に関わる Control のサイズ／ピボット／レイアウトのコンテキストを扱います。
• godot-signal-architecture — Tween の kill と再作成時に接続が残らないよう、完了処理／コールバックの接続を扱います。
• godot-camera-systems — プロシージャルな Tween で動かすカメラ追従、シェイクのオフセット、注視対象を扱います。
• godot-resource-data-patterns — ゲームプレイのスクリプト外に duration／trans／ease を保存する、JuiceConfig 形式の Resource を扱います。
• godot-particles — 並行する場当たり的なタイマーではなく、tween_callback のステップから開始するバーストのタイミングやワンショットの VFX を扱います。
• godot-shaders-basics — プロパティパスだけでは不十分な場合に、tween_method／set でアニメーションさせるシェーダーパラメーターを扱います。

下流／利用側

• godot-inventory-system — 段階的で中断可能な Tween を使った、スロット／アイテムの表示、ドラッグ時のフィードバック、装備時の演出を扱います。
• godot-genre-card-game — Tween の連鎖に依存する、手札の弧を描く動き、ドロー／捨て札の移動、解決処理の仕上げを扱います。
• godot-ui-theming — 同じ Control 内で安全に Tween を中断する必要がある、テーマに基づくホバー／フォーカス時のモーションを扱います。

マスター

• godot-master — スキル横断での発見に使う、ライブラリーのルーター兼ミラー化されたモジュールのエントリです。