tweens

Tweens

Phaser 4 でプロパティを時間経過に沿ってアニメーション化する -- TweenManager、トゥイーンの作成、トゥイーン設定、イージング関数、トゥイーンチェーン、スタッガー、ヨーヨー、リピート、コールバック、トゥイーンターゲット。

主要なソースパス: src/tweens/TweenManager.js、src/tweens/tween/Tween.js、src/tweens/tween/TweenChain.js、src/tweens/tween/BaseTween.js、src/tweens/builders/、src/tweens/typedefs/、src/tweens/events/、src/math/easing/ 関連スキル: ../sprites-and-images/SKILL.md、../animations/SKILL.md

クイックスタート

// In a Scene's create() method:

const logo = this.add.image(100, 300, 'logo');

// Basic tween -- move the logo to x:600 over 2 seconds
this.tweens.add({
    targets: logo,
    x: 600,
    duration: 2000,
    ease: 'Power2'
});

this.tweens はシーンの TweenManager インスタンスで、すべてのシーンで利用できます。add() メソッドはトゥイーンを作成し、マネージャーに追加して、すぐに再生を開始します。

基本概念

トゥイーンのライフサイクル

作成済み -> アクティブ（onActive）-> 遅延開始（delay）-> 再生中（onStart、毎フレーム onUpdate）-> ヨーヨー/リピート（onYoyo、onRepeat）-> ループ（onLoop）-> 完了（onComplete、その後 persist: true でない限り自動的に破棄されます）。

ファイア・アンド・フォーゲット設計

トゥイーンは完了後に自動的に破棄されます。後で制御したい場合を除き、参照を保持する必要はありません。完了後もトゥイーンを存続させ、tween.play() や tween.restart() で再生できるようにするには、設定で persist: true を指定します。永続化したトゥイーンは、不要になった時点で手動で tween.destroy() を呼び出す必要があります。

ターゲット

targets プロパティは、単一のオブジェクト、オブジェクトの配列、またはそのいずれかを返す関数を受け付けます。ターゲットは通常ゲームオブジェクトですが、数値プロパティを持つ任意の JavaScript オブジェクトでもかまいません。トゥイーンはアンダースコアで始まるプロパティを操作しません。

// Single target
this.tweens.add({ targets: sprite, alpha: 0, duration: 500 });

// Multiple targets
this.tweens.add({ targets: [sprite1, sprite2, sprite3], y: 100, duration: 1000 });

プロパティ値

this.tweens.add({
    targets: sprite,
    x: 400,                  // absolute value
    y: '-=100',              // relative (subtract 100 from current)
    rotation: '+=3.14',      // relative (add to current)
    alpha: { value: 0, duration: 300, ease: 'Cubic.easeIn' },  // per-property config
    scale: [0.5, 1.5, 1],   // array: interpolates through values over duration
    angle: function (target, key, value, targetIndex, totalTargets, tween) {
        return targetIndex * 90;   // function: called once per target
    },
    duration: 1000
});

配列の値はデフォルトで線形補間を使用します。interpolation 設定（'linear'、'bezier'、'catmull'）で上書きできます。

一般的なパターン

基本的なトゥイーン

this.tweens.add({
    targets: this.player,
    x: 500,
    y: 300,
    duration: 1000,
    ease: 'Sine.easeInOut'
});

プロパティごとの設定による複数プロパティ

this.tweens.add({
    targets: this.enemy,
    x: { value: 600, duration: 1500, ease: 'Bounce.easeOut' },
    y: { value: 200, duration: 1000, ease: 'Power2' },
    alpha: { value: 0.5, duration: 500, delay: 1000 }
});

ヨーヨーとリピート

this.tweens.add({
    targets: this.coin,
    y: '-=50',
    duration: 600,
    ease: 'Sine.easeInOut',
    yoyo: true,         // returns to start value after reaching end
    hold: 200,          // pause 200ms at the end value before yoyo-ing back
    repeat: -1,         // -1 = infinite, 0 = play once, 1 = play twice, etc.
    repeatDelay: 300     // pause 300ms before each repeat
});

repeat は各プロパティを追加で何回再生するかを制御します。repeat が 1 の場合、トゥイーンは合計 2 回再生されます。loop プロパティ（BaseTween 上）は、すべてのプロパティを含めてトゥイーン全体を最初から再開します。プロパティレベルのループには repeat を、トゥイーンレベルのループには loop を使用してください。

スタッガー

スタッガーは this.tweens.stagger() を通じて、複数のターゲットにわたって値をずらします:

// 100ms delay between each target
delay: this.tweens.stagger(100)

// From center outward
delay: this.tweens.stagger(200, { from: 'center' })

// Range: distribute 0-1000ms across targets
delay: this.tweens.stagger([0, 1000])

// Grid stagger with easing
delay: this.tweens.stagger(500, { grid: [10, 6], from: 'center', ease: 'Cubic.easeOut' })

StaggerConfig: start（オフセット）、ease（文字列/関数）、from（'first'/'center'/'last'/インデックス）、grid（[w, h]）。

トゥイーンチェーン

TweenChain はトゥイーンを順番に再生します。チェーン内の各トゥイーンは、前のトゥイーンが完了した後に開始されます:

this.tweens.chain({
    targets: this.player,
    tweens: [
        { x: 300, duration: 1000, ease: 'Power2' },
        { y: 500, duration: 800, ease: 'Bounce.easeOut' },
        { scale: 2, duration: 500 },
        { alpha: 0, duration: 400 }
    ],
    loop: 1,          // loop the entire chain once (plays twice total)
    loopDelay: 500,
    onComplete: function () {
        console.log('Chain finished');
    }
});

tweens の各エントリは標準の TweenBuilderConfig です。チェーンレベルの設定は loop、loopDelay、completeDelay、paused、persist、およびチェーンレベルのコールバックをサポートします。トゥイーンごとのコールバック（onUpdate、onRepeat、onYoyo）は個々のエントリに記述します。動的に追加するには chain.add(tweenConfigs) を使用します。

相対値

this.tweens.add({
    targets: sprite,
    x: '+=200',    // add 200 to current x
    y: '-=50',     // subtract 50 from current y
    angle: '+=180',
    duration: 1000
});

コールバックとイベント

this.tweens.add({
    targets: sprite,
    x: 600,
    duration: 2000,

    // All callbacks receive (tween, targets, ...params)
    onStart: function (tween, targets) { },
    onUpdate: function (tween, targets) { },     // per-property, per-target, per-frame
    onYoyo: function (tween, targets) { },
    onRepeat: function (tween, targets) { },
    onLoop: function (tween, targets) { },
    onComplete: function (tween, targets) { },

    onCompleteParams: ['extra', 'args'],
    callbackScope: this
});

// Set callback after creation
tween.setCallback('onComplete', function (tween, targets) { }, []);

// Event emitter style (tweens extend EventEmitter)
tween.on('complete', function (tween, targets) { });

数値トゥイーン

数値トゥイーンにはターゲットオブジェクトがありません。2 つの数値の間をトゥイーンします:

const counter = this.tweens.addCounter({
    from: 0,
    to: 100,
    duration: 2000,
    ease: 'Linear',
    onUpdate: function (tween) {
        const value = tween.getValue();
        console.log(value);   // 0 ... 100
    }
});

トゥイーンの制御と停止

const tween = this.tweens.add({ targets: sprite, x: 600, duration: 2000, persist: true });

// Playback control
tween.pause();                  tween.resume();
tween.stop();                   // flags for removal; fires onStop
tween.restart();                // reset and replay from beginning
tween.seek(1000);               // seek to 1000ms (suppresses events by default)
tween.complete();               // immediately complete; fires onComplete
tween.completeAfterLoop(0);     // finish after current loop
tween.forward(500);             tween.rewind(500);
tween.setTimeScale(0.5);       // per-tween speed
tween.updateTo('x', 800);      // change end value mid-tween

// Manager-level control
this.tweens.killAll();                     // destroy all tweens
this.tweens.killTweensOf(sprite);          // destroy tweens on target
this.tweens.isTweening(sprite);            // boolean check
this.tweens.pauseAll();                    this.tweens.resumeAll();
this.tweens.setGlobalTimeScale(0.5);       // global speed

設定リファレンス

TweenBuilderConfig

プロパティ	型	デフォルト	説明
targets	any / any[]	(必須)	トゥイーンするオブジェクト。
duration	number	1000	再生時間 (ミリ秒)。
delay	number / function	0	開始前の遅延 (ミリ秒)。stagger() を受け付けます。
ease	string / function	'Power0'	イージング関数の名前、またはカスタム関数。
easeParams	array	null	パラメーター化されたイージング (例: Elastic) のパラメーター。
hold	number	0	yoyo の前に終了値で保持する時間 (ミリ秒)。
repeat	number	0	プロパティごとのリピート回数。-1 = 無限。
repeatDelay	number	0	各リピート前の遅延 (ミリ秒)。
yoyo	boolean	false	終了値に達した後に開始値へ逆再生します。
flipX / flipY	boolean	false	yoyo/repeat 時のフリップを切り替えます。
loop	number	0	トゥイーン単位のループ回数。-1 = 無限。
loopDelay	number	0	各ループ前の遅延 (ミリ秒)。
completeDelay	number	0	onComplete が発火する前の遅延 (ミリ秒)。
paused	boolean	false	一時停止状態で開始します。開始するには play() を呼び出します。
persist	boolean	false	完了後も維持します。
props	object	--	明示的なプロパティ設定マップ (トップレベルプロパティの代替)。
interpolation	string / function	--	配列値用: 'linear'、'bezier'、'catmull'。
callbackScope	any	tween	コールバックの this コンテキスト。
Callbacks	function	--	onActive、onStart、onUpdate、onYoyo、onRepeat、onLoop、onComplete、onStop、onPause、onResume。それぞれに対応する on<Name>Params 配列があります。

TweenChainBuilderConfig

プロパティ	型	デフォルト	説明
targets	any / any[]	--	子トゥイーンが継承するデフォルトのターゲット。
tweens	TweenBuilderConfig[]	(必須)	順番に再生するトゥイーン設定の配列。
loop	number	0	チェーン全体をループする回数。-1 = 無限。
loopDelay	number	0	各ループ前の遅延 (ミリ秒)。
completeDelay	number	0	onComplete が発火する前の遅延 (ミリ秒)。
paused	boolean	false	一時停止状態で開始します。
persist	boolean	false	完了後も維持します。
Callbacks	function	--	onActive、onStart、onLoop、onComplete、onStop、onPause、onResume。

NumberTweenBuilderConfig

プロパティ	型	デフォルト	説明
from	number	0	開始値。
to	number	1	終了値。
duration	number	1000	再生時間 (ミリ秒)。
ease	string / function	'Power0'	イージング関数。
All standard timing	--	--	delay、hold、repeat、repeatDelay、yoyo、loop、loopDelay、completeDelay、paused、persist。
All standard callbacks	--	--	TweenBuilderConfig と同じコールバックセット。

TweenPropConfig (プロパティごとのオブジェクト)

プロパティの値が数値や文字列ではなくオブジェクトの場合に使用します。value、getActive、getEnd、getStart、ease、delay、duration、yoyo、hold、repeat、repeatDelay、flipX、flipY、interpolation をサポートします。いずれもその 1 つのプロパティについてトゥイーン単位のデフォルトを上書きします。

イージング関数

すべてのイージング名は大文字と小文字を区別しません。ease 設定プロパティで文字列名を使用します。

Power エイリアス

名前	同等
Power0	Linear
Power1	Quad.easeOut (Quadratic Out)
Power2	Cubic.easeOut
Power3	Quart.easeOut (Quartic Out)
Power4	Quint.easeOut (Quintic Out)

イージング一覧

各タイプは .easeIn、.easeOut、.easeInOut のバリアントをサポートします。名前のみの場合はデフォルトで Out になります。

タイプ: Quad、Cubic、Quart、Quint、Sine、Expo、Circ、Elastic、Back、Bounce。

使用方法: 'Sine.easeInOut'、'Bounce.easeIn'、'Cubic.easeOut'、'Back' ('Back.easeOut' と同じ)。

特殊: Linear (イージングなし)、Stepped (離散ステップ -- easeParams: [numSteps])。

カスタム: ease: function (t) { return t * t; }。ここで t は 0 から 1 です。

イベント

Tween（および TweenChain）は EventEmitter を拡張しています。.on() を介してリッスンできます:

イベント文字列	定数	発火タイミング
'active'	Phaser.Tweens.Events.TWEEN_ACTIVE	Tween がマネージャーに追加されたとき
'start'	Phaser.Tweens.Events.TWEEN_START	再生が開始されたとき（遅延の後）
'update'	Phaser.Tweens.Events.TWEEN_UPDATE	毎フレームでプロパティが更新されたとき
'yoyo'	Phaser.Tweens.Events.TWEEN_YOYO	プロパティが yoyo で戻り始めたとき
'repeat'	Phaser.Tweens.Events.TWEEN_REPEAT	プロパティがリピートされたとき
'loop'	Phaser.Tweens.Events.TWEEN_LOOP	Tween 全体がループしたとき
'complete'	Phaser.Tweens.Events.TWEEN_COMPLETE	Tween が完了したとき
'stop'	Phaser.Tweens.Events.TWEEN_STOP	tween.stop() が呼ばれたとき
'pause'	Phaser.Tweens.Events.TWEEN_PAUSE	tween.pause() が呼ばれたとき
'resume'	Phaser.Tweens.Events.TWEEN_RESUME	tween.resume() が呼ばれたとき

Tween イベントのイベントリスナーのシグネチャ: function(tween, targets)。シーク中（tween.isSeeking === true）は、イベントとコールバックはデフォルトで抑制されます。

API クイックリファレンス

TweenManager (this.tweens)

メソッド	戻り値	目的
add(config)	Tween	Tween を作成、追加、開始します。
addMultiple(configs[])	Tween[]	複数の Tween を一度に作成します。
create(config)	Tween	追加せずに作成します。後で追加するには existing() を使用します。
chain(config)	TweenChain	シーケンシャルなチェーンを作成して開始します。
addCounter(config)	Tween	数値 Tween（ターゲットなし）。
stagger(value, config?)	function	delay/property 値用のスタッガー関数。
existing(tween)	this	事前に作成した Tween をマネージャーに追加します。
remove(tween)	this	破棄せずに削除します。
has(tween)	boolean	Tween がマネージャー内にあるか確認します。
getTweens()	Tween[]	すべてのアクティブな Tween（コピー）。
getTweensOf(target)	Tween[]	ターゲットに影響する Tween。
isTweening(target)	boolean	ターゲットが Tween 中かどうか。
killAll() / killTweensOf(target)	this	Tween を破棄します。
pauseAll() / resumeAll()	this	すべての Tween を一時停止/再開します。
setGlobalTimeScale(v) / getGlobalTimeScale()	this / number	グローバル速度。
setFps(fps)	this	ティックレートを制限します（デフォルト 240）。
setLagSmooth(limit, skip)	this	ラグスムージングを設定します。
each(cb, scope)	this	すべての Tween を反復します。

Tween インスタンス

メソッド	目的
play() / pause() / resume()	再生コントロール。
stop()	停止し、削除対象としてフラグを立てます。onStop を発火します。
restart()	リセットして再再生します。
complete(delay?)	即座に完了します。
completeAfterLoop(loops?)	さらに N 回ループした後に完了します。
seek(ms, delta?, emit?)	ms オフセットにシークします。
forward(ms) / rewind(ms)	前進/後退します。
setTimeScale(v) / getTimeScale()	Tween ごとの速度。
setCallback(type, fn, params?)	作成後にコールバックを設定します。
getValue(index?)	現在の TweenData 値。
updateTo(key, value, startToCurrent?)	Tween の途中で終了値を変更します。
hasTarget(target) / isPlaying() / isPaused()	状態チェック。
remove() / destroy()	クリーンアップ。

主なプロパティ: targets、duration、elapsed、progress（0-1）、totalProgress（ループを含む 0-1）、totalDuration、timeScale、paused、persist、data（TweenData[]）、isInfinite、isNumberTween。

TweenChain インスタンス

BaseTween を拡張しています。すべての Tween 再生メソッド（play、pause、resume、stop、restart、complete など）に加えて、Tween を動的に追加する add(tweenConfigs) を持ちます。プロパティ: currentTween、currentIndex。

注意点

• アンダースコア付きのプロパティは無視されます。 Tween は、名前が _ で始まるプロパティをスキップします。
• Tween は自動的に破棄されます。 Tween への参照を保持し、完了後にそれを使おうとすると、破棄されている可能性があります。persist: true を設定すれば存続させられますが、使い終わったら自分で destroy() する必要があります。
• repeat と loop の違い。 repeat はプロパティごと（TweenData 上）です。loop は Tween 全体を再開します。repeat が 1 の場合、そのプロパティは合計 2 回再生されます。
• loop: -1 は onComplete が決して発火しないことを意味します。 無限ループする Tween は決して完了しません。gracefully に終了させるには completeAfterLoop() を使用してください。
• シークはイベントを抑制します。 tween.seek() を呼び出すと、3 番目の引数に true を渡さない限り、イベントとコールバックはディスパッチされません。
• スタッガーは複数のターゲットでのみ機能します。 単一ターゲットの Tween で this.tweens.stagger() を使っても、目に見えるスタッガー効果はありません。
• 破棄されたターゲット。 ターゲットの isDestroyed が true に設定されている場合、Tween は早期に完了します。参照するオブジェクトを破棄する前に必ず Tween をクリーンアップするか、この自動チェックに頼ってください。
• TweenManager.timeScale は Tween.timeScale と乗算されます。 実効速度は managerTimeScale * tweenTimeScale です。どちらかを 0 に設定すると Tween はフリーズします。
• duration は 0 にできません。 内部的に最小 0.01ms にクランプされます。
• TweenChain の targets は継承されます。 チェーンレベルで targets を設定すると、チェーン内の個々の Tween は独自に指定しない限りそれを継承します。

ソースファイルマップ

ファイル	目的
src/tweens/TweenManager.js	シーンプラグイン。add、chain、stagger、killAll など。
src/tweens/tween/Tween.js	個々の Tween。ターゲット、TweenData 配列、シーク、更新。
src/tweens/tween/TweenChain.js	順序付けられた子 Tween による逐次 Tween 再生。
src/tweens/tween/BaseTween.js	共有ベース。EventEmitter、コールバック、ステートマシン。
src/tweens/tween/BaseTweenData.js	プロパティごとの状態：duration、delay、yoyo、repeat、progress。
src/tweens/tween/TweenData.js	数値プロパティのトゥイーン（BaseTweenData を継承）。
src/tweens/tween/TweenFrameData.js	テクスチャフレームのトゥイーン（BaseTweenData を継承）。
src/tweens/builders/TweenBuilder.js	設定を解析して Tween インスタンスを生成。
src/tweens/builders/TweenChainBuilder.js	設定を解析して TweenChain インスタンスを生成。
src/tweens/builders/NumberTweenBuilder.js	ターゲットを持たない数値 Tween を生成。
src/tweens/builders/StaggerBuilder.js	スタッガー関数を生成。
src/tweens/events/	イベント定数（TWEEN_ACTIVE、TWEEN_START など）。
src/tweens/typedefs/	すべての設定オブジェクトの JSDoc typedef。
src/math/easing/EaseMap.js	ease 文字列名を関数にマッピング。