tweens

用途

本技能用于在 Phaser 4 中随时间动画化对象属性。它围绕 TweenManager（场景中的 this.tweens）展开，涵盖补间创建、配置、缓动、链式播放、错峰（stagger）、往复（yoyo）、重复（repeat）、回调与事件，以及补间目标的管理。

主要能力

补间创建：this.tweens.add() 创建、加入管理器并立即播放；addMultiple() 批量创建；create() 仅创建不加入；addCounter() 创建无目标的数值补间；chain() 创建顺序播放的补间链。
目标（targets）：接受单个对象、对象数组或返回二者的函数；目标通常是游戏对象，但也可以是任何带数值属性的 JavaScript 对象；以下划线开头的属性不会被操作。
属性值：支持绝对值、相对值（'+=100'、'-=100'）、逐属性配置对象（value、duration、ease、delay 等）、数组值（默认线性插值，可用 interpolation 指定 'linear'、'bezier'、'catmull'）以及函数值（每个目标调用一次）。
缓动：ease 接受字符串名或自定义函数；名称不区分大小写；Power0 等价 Linear，Power1 等价 Quad.easeOut，Power2 等价 Cubic.easeOut，Power3 等价 Quart.easeOut，Power4 等价 Quint.easeOut；完整类型包括 Quad、Cubic、Quart、Quint、Sine、Expo、Circ、Elastic、Back、Bounce，各支持 .easeIn、.easeOut、.easeInOut，裸名默认 Out；另有 Linear、Stepped（easeParams: [numSteps]）与自定义函数。
错峰：this.tweens.stagger() 为多目标偏移延迟或属性值，支持固定间隔、范围数组、from（'first'/'center'/'last'/索引）、grid（[w, h]）与 ease。
补间链：this.tweens.chain() 按顺序播放多个补间，每个在前一个完成后开始；链级配置支持 loop、loopDelay、completeDelay、paused、persist 与链级回调；可用 chain.add() 动态追加。
回调与事件：onActive、onStart、onUpdate、onYoyo、onRepeat、onLoop、onComplete、onStop、onPause、onResume，均有对应的 on<Name>Params；补间继承 EventEmitter，可用 .on() 监听 'active'、'start'、'update'、'yoyo'、'repeat'、'loop'、'complete'、'stop'、'pause'、'resume' 等事件。
控制：实例级 play、pause、resume、stop、restart、complete、completeAfterLoop、seek、forward、rewind、setTimeScale、updateTo、getValue、setCallback、remove、destroy；管理器级 killAll、killTweensOf、isTweening、pauseAll、resumeAll、setGlobalTimeScale、setFps、setLagSmooth、each 等。

使用方式

在 Scene 的 create() 方法中通过 this.tweens 使用。基本示例：

const logo = this.add.image(100, 300, 'logo');
this.tweens.add({
  targets: logo,
  x: 600,
  duration: 2000,
  ease: 'Power2'
});

补间默认“发射后不管”，完成后自动销毁；如需后续控制，设置 persist: true 并在用完后手动 destroy()。

适用场景

适用于游戏或交互应用中的属性动画：移动、缩放、旋转、透明度变化、数值计数、多目标错峰动画、按顺序编排的动画序列等。

限制与注意事项

下划线开头的属性会被忽略。
补间完成后自动销毁，保存的引用可能已失效；persist: true 需自行销毁。
repeat 是逐属性（TweenData）级别，loop 是补间级别；repeat 为 1 表示属性总共播放两次。
loop: -1 时 onComplete 永不触发，可用 completeAfterLoop() 优雅结束。
seek() 默认抑制事件与回调，除非第三个参数传 true。
stagger 仅在多目标时有效。
目标 isDestroyed 为 true 时补间提前完成。
有效速度 = 管理器 timeScale × 补间 timeScale，任一为 0 即冻结。
duration 不能为 0，内部最小钳制为 0.01ms。
补间链的目标会被子补间继承，除非子补间自行指定。

关键源码路径

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。