Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat: add JS-side value tween for custom property animation

esenginecd0d1089a66d
diff --git a/docs/astro/src/content/docs/guides/tween.mdx b/docs/astro/src/content/docs/guides/tween.mdx
new file mode 100644
index 000000000..9e346fa3a
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/tween.mdx
@@ -0,0 +1,272 @@
+---
+title: Tween Animation
+description: Property tweening in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The Tween system animates entity properties over time — position, scale, rotation, color, size, and camera ortho size. The `AnimationPlugin` is included by the engine by default.
+
+## Basic Usage
+
+Use `Tween.to()` to animate a property from one value to another:
+
+```typescript
+import { Tween, TweenTarget } from 'esengine';
+
+// Move entity to x=200 over 1 second
+Tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0);
+
+// Fade out sprite over 0.5 seconds
+Tween.to(entity, TweenTarget.ColorA, 1, 0, 0.5);
+
+// Scale up over 0.3 seconds
+Tween.to(entity, TweenTarget.ScaleX, 1, 2, 0.3);
+Tween.to(entity, TweenTarget.ScaleY, 1, 2, 0.3);
+```
+
+### Parameters
+
+```typescript
+Tween.to(entity, target, from, to, duration, options?)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `entity` | Entity | Target entity |
+| `target` | TweenTarget | Property to animate |
+| `from` | number | Start value |
+| `to` | number | End value |
+| `duration` | number | Duration in seconds |
+| `options` | TweenOptions | Optional easing, delay, loop config |
+
+## Tween Targets
+
+| Target | Property |
+|--------|----------|
+| `PositionX` | Transform position X |
+| `PositionY` | Transform position Y |
+| `PositionZ` | Transform position Z |
+| `ScaleX` | Transform scale X |
+| `ScaleY` | Transform scale Y |
+| `RotationZ` | Transform rotation around Z axis (radians) |
+| `ColorR` | Sprite color red (0–1) |
+| `ColorG` | Sprite color green (0–1) |
+| `ColorB` | Sprite color blue (0–1) |
+| `ColorA` | Sprite color alpha (0–1) |
+| `SizeX` | Sprite width |
+| `SizeY` | Sprite height |
+| `CameraOrthoSize` | Camera orthographic size |
+
+## Easing
+
+Pass an `easing` option to control the animation curve:
+
+```typescript
+import { Tween, TweenTarget, EasingType } from 'esengine';
+
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0, {
+ easing: EasingType.EaseOutCubic,
+});
+```
+
+### Available Easing Types
+
+| Easing | Description |
+|--------|-------------|
+| `Linear` | Constant speed (default) |
+| `EaseInQuad` | Slow start, accelerating |
+| `EaseOutQuad` | Fast start, decelerating |
+| `EaseInOutQuad` | Slow start and end |
+| `EaseInCubic` | Slow start, steeper acceleration |
+| `EaseOutCubic` | Fast start, steeper deceleration |
+| `EaseInOutCubic` | Smooth start and end |
+| `EaseInBack` | Pulls back before moving forward |
+| `EaseOutBack` | Overshoots then settles |
+| `EaseInOutBack` | Pull back + overshoot |
+| `EaseInElastic` | Elastic wind-up |
+| `EaseOutElastic` | Elastic settle |
+| `EaseInOutElastic` | Elastic both ends |
+| `EaseOutBounce` | Bouncing settle |
+| `CubicBezier` | Custom curve via control points |
+| `Step` | Instant jump (no interpolation) |
+
+### Custom Bezier Curve
+
+Use `CubicBezier` easing with `.bezier()` to define a custom curve:
+
+```typescript
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0, {
+ easing: EasingType.CubicBezier,
+}).bezier(0.25, 0.1, 0.25, 1.0);
+```
+
+## Delay
+
+Start a tween after a delay:
+
+```typescript
+Tween.to(entity, TweenTarget.ColorA, 1, 0, 0.5, {
+ delay: 1.0, // wait 1 second before fading
+});
+```
+
+## Looping
+
+```typescript
+import { Tween, TweenTarget, LoopMode } from 'esengine';
+
+// Loop forever (ping-pong)
+Tween.to(entity, TweenTarget.PositionY, 0, 50, 2.0, {
+ loop: LoopMode.PingPong,
+});
+
+// Loop 3 times then stop
+Tween.to(entity, TweenTarget.ScaleX, 1, 1.5, 0.5, {
+ loop: LoopMode.Restart,
+ loopCount: 3,
+});
+```
+
+| Mode | Behavior |
+|------|----------|
+| `None` | Plays once (default) |
+| `Restart` | Resets to start value and replays |
+| `PingPong` | Reverses direction each iteration |
+
+Set `loopCount` to limit iterations. Omit it for infinite looping.
+
+## Sequencing
+
+Chain tweens so they play one after another with `.then()`:
+
+```typescript
+const moveRight = Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0);
+const moveDown = Tween.to(entity, TweenTarget.PositionY, 0, 100, 1.0);
+
+moveRight.then(moveDown);
+```
+
+Or chain fluently:
+
+```typescript
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0)
+ .then(Tween.to(entity, TweenTarget.PositionY, 0, 100, 1.0));
+```
+
+<Aside type="note">
+Without `.then()`, tweens created at the same time run in parallel. Use `.then()` only when you need sequential playback.
+</Aside>
+
+## Controlling Tweens
+
+`Tween.to()` returns a `TweenHandle` for runtime control:
+
+```typescript
+const handle = Tween.to(entity, TweenTarget.PositionX, 0, 100, 2.0);
+
+handle.pause(); // pause
+handle.resume(); // resume
+handle.cancel(); // cancel and remove
+
+// Check state
+if (handle.state === TweenState.Running) {
+ // still animating
+}
+```
+
+### TweenState
+
+| State | Meaning |
+|-------|---------|
+| `Running` | Currently animating |
+| `Paused` | Paused, can resume |
+| `Completed` | Finished playing |
+| `Cancelled` | Cancelled, will be removed |
+
+## Cancelling Tweens
+
+Cancel a single tween or all tweens on an entity:
+
+```typescript
+import { Tween } from 'esengine';
+
+// Cancel one
+handle.cancel();
+
+// Cancel all tweens on an entity
+Tween.cancelAll(entity);
+```
+
+## Custom Property Animation
+
+Use `Tween.value()` to animate any numeric value with a callback:
+
+```typescript
+import { Tween, EasingType } from 'esengine';
+
+// Animate a custom property
+const handle = Tween.value(0, 100, 1.0, (v) => {
+ health.hp = v;
+}, { easing: EasingType.EaseOutQuad });
+
+// Supports all tween features
+handle.pause();
+handle.resume();
+handle.cancel();
+```
+
+### Parameters
+
+```typescript
+Tween.value(from, to, duration, callback, options?)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `from` | number | Start value |
+| `to` | number | End value |
+| `duration` | number | Duration in seconds |
+| `callback` | `(value: number) => void` | Called each frame with the interpolated value |
+| `options` | TweenOptions | Optional easing, delay, loop config |
+
+### Custom Bezier Curve
+
+Use `CubicBezier` easing with `.bezier()` on value tweens:
+
+```typescript
+Tween.value(0, 100, 1.0, (v) => { progress = v; }, {
+ easing: EasingType.CubicBezier,
+}).bezier(0.25, 0.1, 0.25, 1.0);
+```
+
+### Sequencing with Built-in Tweens
+
+Value tweens can be chained with built-in property tweens using `.then()`:
+
+```typescript
+// Move entity, then animate custom value
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0)
+ .then(Tween.value(0, 1, 0.5, (v) => { shield.opacity = v; }));
+
+// Animate custom value, then scale entity
+Tween.value(0, 360, 1.0, (v) => { rotation = v; })
+ .then(Tween.to(entity, TweenTarget.ScaleX, 1, 2, 0.5));
+```
+
+### Looping Value Tweens
+
+```typescript
+import { Tween, LoopMode } from 'esengine';
+
+// Infinite ping-pong
+Tween.value(0, 1, 2.0, (v) => { pulse = v; }, {
+ loop: LoopMode.PingPong,
+});
+
+// Loop 3 times
+Tween.value(0, 360, 1.0, (v) => { angle = v; }, {
+ loop: LoopMode.Restart,
+ loopCount: 3,
+});
+```
diff --git a/docs/astro/src/content/docs/zh/guides/tween.mdx b/docs/astro/src/content/docs/zh/guides/tween.mdx
new file mode 100644
index 000000000..d2a3ae9c2
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/tween.mdx
@@ -0,0 +1,272 @@
+---
+title: 补间动画
+description: ESEngine 中的属性补间动画
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Tween 系统可以随时间动画化实体属性 — 位置、缩放、旋转、颜色、尺寸和相机正交大小。`AnimationPlugin` 由引擎默认包含。
+
+## 基本用法
+
+使用 `Tween.to()` 将属性从一个值动画到另一个值:
+
+```typescript
+import { Tween, TweenTarget } from 'esengine';
+
+// 1 秒内将实体移动到 x=200
+Tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0);
+
+// 0.5 秒内淡出精灵
+Tween.to(entity, TweenTarget.ColorA, 1, 0, 0.5);
+
+// 0.3 秒内放大
+Tween.to(entity, TweenTarget.ScaleX, 1, 2, 0.3);
+Tween.to(entity, TweenTarget.ScaleY, 1, 2, 0.3);
+```
+
+### 参数
+
+```typescript
+Tween.to(entity, target, from, to, duration, options?)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `entity` | Entity | 目标实体 |
+| `target` | TweenTarget | 要动画的属性 |
+| `from` | number | 起始值 |
+| `to` | number | 结束值 |
+| `duration` | number | 持续时间(秒) |
+| `options` | TweenOptions | 可选的缓动、延迟、循环配置 |
+
+## 可动画属性
+
+| 目标 | 属性 |
+|------|------|
+| `PositionX` | Transform 位置 X |
+| `PositionY` | Transform 位置 Y |
+| `PositionZ` | Transform 位置 Z |
+| `ScaleX` | Transform 缩放 X |
+| `ScaleY` | Transform 缩放 Y |
+| `RotationZ` | Transform 绕 Z 轴旋转(弧度) |
+| `ColorR` | Sprite 颜色红通道(0–1) |
+| `ColorG` | Sprite 颜色绿通道(0–1) |
+| `ColorB` | Sprite 颜色蓝通道(0–1) |
+| `ColorA` | Sprite 颜色透明度(0–1) |
+| `SizeX` | Sprite 宽度 |
+| `SizeY` | Sprite 高度 |
+| `CameraOrthoSize` | 相机正交大小 |
+
+## 缓动函数
+
+传入 `easing` 选项控制动画曲线:
+
+```typescript
+import { Tween, TweenTarget, EasingType } from 'esengine';
+
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0, {
+ easing: EasingType.EaseOutCubic,
+});
+```
+
+### 可用缓动类型
+
+| 缓动 | 说明 |
+|------|------|
+| `Linear` | 匀速(默认) |
+| `EaseInQuad` | 慢启动,加速 |
+| `EaseOutQuad` | 快启动,减速 |
+| `EaseInOutQuad` | 慢启慢停 |
+| `EaseInCubic` | 慢启动,更陡加速 |
+| `EaseOutCubic` | 快启动,更陡减速 |
+| `EaseInOutCubic` | 平滑启停 |
+| `EaseInBack` | 先回拉再前进 |
+| `EaseOutBack` | 超越后回弹 |
+| `EaseInOutBack` | 回拉 + 超越 |
+| `EaseInElastic` | 弹性蓄力 |
+| `EaseOutElastic` | 弹性回弹 |
+| `EaseInOutElastic` | 两端弹性 |
+| `EaseOutBounce` | 弹跳回弹 |
+| `CubicBezier` | 自定义贝塞尔曲线 |
+| `Step` | 瞬间跳变(无插值) |
+
+### 自定义贝塞尔曲线
+
+使用 `CubicBezier` 缓动配合 `.bezier()` 定义自定义曲线:
+
+```typescript
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0, {
+ easing: EasingType.CubicBezier,
+}).bezier(0.25, 0.1, 0.25, 1.0);
+```
+
+## 延迟
+
+延迟后开始补间:
+
+```typescript
+Tween.to(entity, TweenTarget.ColorA, 1, 0, 0.5, {
+ delay: 1.0, // 等待 1 秒后开始淡出
+});
+```
+
+## 循环
+
+```typescript
+import { Tween, TweenTarget, LoopMode } from 'esengine';
+
+// 无限循环(来回)
+Tween.to(entity, TweenTarget.PositionY, 0, 50, 2.0, {
+ loop: LoopMode.PingPong,
+});
+
+// 循环 3 次后停止
+Tween.to(entity, TweenTarget.ScaleX, 1, 1.5, 0.5, {
+ loop: LoopMode.Restart,
+ loopCount: 3,
+});
+```
+
+| 模式 | 行为 |
+|------|------|
+| `None` | 播放一次(默认) |
+| `Restart` | 重置到起始值重新播放 |
+| `PingPong` | 每次迭代反转方向 |
+
+设置 `loopCount` 限制迭代次数。省略则无限循环。
+
+## 序列播放
+
+用 `.then()` 链接补间使它们依次播放:
+
+```typescript
+const moveRight = Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0);
+const moveDown = Tween.to(entity, TweenTarget.PositionY, 0, 100, 1.0);
+
+moveRight.then(moveDown);
+```
+
+或流式链接:
+
+```typescript
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0)
+ .then(Tween.to(entity, TweenTarget.PositionY, 0, 100, 1.0));
+```
+
+<Aside type="note">
+没有 `.then()` 时,同时创建的补间会并行运行。只在需要顺序播放时使用 `.then()`。
+</Aside>
+
+## 控制补间
+
+`Tween.to()` 返回 `TweenHandle` 用于运行时控制:
+
+```typescript
+const handle = Tween.to(entity, TweenTarget.PositionX, 0, 100, 2.0);
+
+handle.pause(); // 暂停
+handle.resume(); // 恢复
+handle.cancel(); // 取消并移除
+
+// 检查状态
+if (handle.state === TweenState.Running) {
+ // 仍在动画中
+}
+```
+
+### TweenState
+
+| 状态 | 含义 |
+|------|------|
+| `Running` | 正在动画 |
+| `Paused` | 已暂停,可恢复 |
+| `Completed` | 播放完毕 |
+| `Cancelled` | 已取消,将被移除 |
+
+## 取消补间
+
+取消单个补间或实体上的所有补间:
+
+```typescript
+import { Tween } from 'esengine';
+
+// 取消单个
+handle.cancel();
+
+// 取消实体上所有补间
+Tween.cancelAll(entity);
+```
+
+## 自定义属性动画
+
+使用 `Tween.value()` 通过回调动画化任意数值:
+
+```typescript
+import { Tween, EasingType } from 'esengine';
+
+// 动画化自定义属性
+const handle = Tween.value(0, 100, 1.0, (v) => {
+ health.hp = v;
+}, { easing: EasingType.EaseOutQuad });
+
+// 支持所有补间功能
+handle.pause();
+handle.resume();
+handle.cancel();
+```
+
+### 参数
+
+```typescript
+Tween.value(from, to, duration, callback, options?)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `from` | number | 起始值 |
+| `to` | number | 结束值 |
+| `duration` | number | 持续时间(秒) |
+| `callback` | `(value: number) => void` | 每帧调用,传入插值后的值 |
+| `options` | TweenOptions | 可选的缓动、延迟、循环配置 |
+
+### 自定义贝塞尔曲线
+
+对值补间使用 `CubicBezier` 缓动配合 `.bezier()`:
+
+```typescript
+Tween.value(0, 100, 1.0, (v) => { progress = v; }, {
+ easing: EasingType.CubicBezier,
+}).bezier(0.25, 0.1, 0.25, 1.0);
+```
+
+### 与内置补间的序列链接
+
+值补间可以通过 `.then()` 与内置属性补间链接:
+
+```typescript
+// 先移动实体,再动画化自定义值
+Tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0)
+ .then(Tween.value(0, 1, 0.5, (v) => { shield.opacity = v; }));
+
+// 先动画化自定义值,再缩放实体
+Tween.value(0, 360, 1.0, (v) => { rotation = v; })
+ .then(Tween.to(entity, TweenTarget.ScaleX, 1, 2, 0.5));
+```
+
+### 循环值补间
+
+```typescript
+import { Tween, LoopMode } from 'esengine';
+
+// 无限来回
+Tween.value(0, 1, 2.0, (v) => { pulse = v; }, {
+ loop: LoopMode.PingPong,
+});
+
+// 循环 3 次
+Tween.value(0, 360, 1.0, (v) => { angle = v; }, {
+ loop: LoopMode.Restart,
+ loopCount: 3,
+});
+```
diff --git a/sdk/src/animation/Tween.ts b/sdk/src/animation/Tween.ts
index a550885c4..bb94b182b 100644
--- a/sdk/src/animation/Tween.ts
+++ b/sdk/src/animation/Tween.ts
@@ -4,34 +4,24 @@
*/
import type { Entity } from '../types';
-import type { World } from '../world';
import type { ESEngineModule, CppRegistry } from '../wasm';
+import {
+ EasingType,
+ TweenState,
+ LoopMode,
+ valueTweenManager,
+ ValueTweenHandle,
+} from './ValueTween';
+import type { TweenOptions, BezierPoints } from './ValueTween';
+
+// Re-export shared types from ValueTween for backward compatibility
+export { EasingType, TweenState, LoopMode, ValueTweenHandle } from './ValueTween';
+export type { TweenOptions, BezierPoints } from './ValueTween';
// =============================================================================
-// Enums (must match C++ TweenData.hpp)
+// Tween Target (C++ specific)
// =============================================================================
-export const EasingType = {
- Linear: 0,
- EaseInQuad: 1,
- EaseOutQuad: 2,
- EaseInOutQuad: 3,
- EaseInCubic: 4,
- EaseOutCubic: 5,
- EaseInOutCubic: 6,
- EaseInBack: 7,
- EaseOutBack: 8,
- EaseInOutBack: 9,
- EaseInElastic: 10,
- EaseOutElastic: 11,
- EaseInOutElastic: 12,
- EaseOutBounce: 13,
- CubicBezier: 14,
- Step: 15,
-} as const;
-
-export type EasingType = (typeof EasingType)[keyof typeof EasingType];
-
export const TweenTarget = {
PositionX: 0,
PositionY: 1,
@@ -50,41 +40,6 @@ export const TweenTarget = {
export type TweenTarget = (typeof TweenTarget)[keyof typeof TweenTarget];
-export const TweenState = {
- Running: 0,
- Paused: 1,
- Completed: 2,
- Cancelled: 3,
-} as const;
-
-export type TweenState = (typeof TweenState)[keyof typeof TweenState];
-
-export const LoopMode = {
- None: 0,
- Restart: 1,
- PingPong: 2,
-} as const;
-
-export type LoopMode = (typeof LoopMode)[keyof typeof LoopMode];
-
-// =============================================================================
-// Tween Options
-// =============================================================================
-
-export interface TweenOptions {
- easing?: EasingType;
- delay?: number;
- loop?: LoopMode;
- loopCount?: number;
-}
-
-export interface BezierPoints {
- p1x: number;
- p1y: number;
- p2x: number;
- p2y: number;
-}
-
// =============================================================================
// Tween Handle (fluent builder)
// =============================================================================
@@ -109,7 +64,11 @@ export class TweenHandle {
return this;
}
- then(next: TweenHandle): this {
+ then(next: TweenHandle | ValueTweenHandle): this {
+ if (next instanceof ValueTweenHandle) {
+ valueTweenManager.registerCppSequence(this.entity, next.id);
+ return this;
+ }
this.module_._anim_setSequenceNext(this.registry_, this.entity, next.entity);
return this;
}
@@ -137,9 +96,11 @@ let _registry: CppRegistry | null = null;
export function initTweenAPI(module: ESEngineModule, registry: CppRegistry): void {
_module = module;
_registry = registry;
+ valueTweenManager.init(module, registry);
}
export function shutdownTweenAPI(): void {
+ valueTweenManager.shutdown();
_module = null;
_registry = null;
}
@@ -172,6 +133,13 @@ export const Tween = {
return new TweenHandle(m, r, tweenEntity);
},
+ value(from: number, to: number, duration: number,
+ callback: (value: number) => void,
+ options?: TweenOptions): ValueTweenHandle {
+ const id = valueTweenManager.create(from, to, duration, callback, options);
+ return new ValueTweenHandle(id);
+ },
+
cancel(tweenHandle: TweenHandle): void {
getModule()._anim_cancelTween(getRegistry(), tweenHandle.entity);
},
@@ -182,5 +150,6 @@ export const Tween = {
update(deltaTime: number): void {
getModule()._anim_updateTweens(getRegistry(), deltaTime);
+ valueTweenManager.update(deltaTime);
},
-} as const;
+};
diff --git a/sdk/src/animation/ValueTween.ts b/sdk/src/animation/ValueTween.ts
new file mode 100644
index 000000000..5ca41c60c
--- /dev/null
+++ b/sdk/src/animation/ValueTween.ts
@@ -0,0 +1,437 @@
+/**
+ * @file ValueTween.ts
+ * @brief JS-side value tweening with easing functions ported from C++
+ */
+
+import type { ESEngineModule, CppRegistry } from '../wasm';
+import type { Entity } from '../types';
+
+// =============================================================================
+// Enums (must match C++ TweenData.hpp)
+// =============================================================================
+
+export const EasingType = {
+ Linear: 0,
+ EaseInQuad: 1,
+ EaseOutQuad: 2,
+ EaseInOutQuad: 3,
+ EaseInCubic: 4,
+ EaseOutCubic: 5,
+ EaseInOutCubic: 6,
+ EaseInBack: 7,
+ EaseOutBack: 8,
+ EaseInOutBack: 9,
+ EaseInElastic: 10,
+ EaseOutElastic: 11,
+ EaseInOutElastic: 12,
+ EaseOutBounce: 13,
+ CubicBezier: 14,
+ Step: 15,
+} as const;
+
+export type EasingType = (typeof EasingType)[keyof typeof EasingType];
+
+export const TweenState = {
+ Running: 0,
+ Paused: 1,
+ Completed: 2,
+ Cancelled: 3,
+} as const;
+
+export type TweenState = (typeof TweenState)[keyof typeof TweenState];
+
+export const LoopMode = {
+ None: 0,
+ Restart: 1,
+ PingPong: 2,
+} as const;
+
+export type LoopMode = (typeof LoopMode)[keyof typeof LoopMode];
+
+export interface TweenOptions {
+ easing?: EasingType;
+ delay?: number;
+ loop?: LoopMode;
+ loopCount?: number;
+}
+
+export interface BezierPoints {
+ p1x: number;
+ p1y: number;
+ p2x: number;
+ p2y: number;
+}
+
+// =============================================================================
+// Easing Functions (1:1 port from C++ EasingFunctions.hpp)
+// =============================================================================
+
+function easeLinear(t: number): number {
+ return t;
+}
+
+function easeInQuad(t: number): number {
+ return t * t;
+}
+
+function easeOutQuad(t: number): number {
+ return t * (2 - t);
+}
+
+function easeInOutQuad(t: number): number {
+ return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+}
+
+function easeInCubic(t: number): number {
+ return t * t * t;
+}
+
+function easeOutCubic(t: number): number {
+ const t1 = t - 1;
+ return t1 * t1 * t1 + 1;
+}
+
+function easeInOutCubic(t: number): number {
+ return t < 0.5
+ ? 4 * t * t * t
+ : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
+}
+
+const BACK_C1 = 1.70158;
+const BACK_C3 = BACK_C1 + 1;
+const BACK_C2 = BACK_C1 * 1.525;
+
+function easeInBack(t: number): number {
+ return BACK_C3 * t * t * t - BACK_C1 * t * t;
+}
+
+function easeOutBack(t: number): number {
+ const t1 = t - 1;
+ return 1 + BACK_C3 * t1 * t1 * t1 + BACK_C1 * t1 * t1;
+}
+
+function easeInOutBack(t: number): number {
+ if (t < 0.5) {
+ return (Math.pow(2 * t, 2) * ((BACK_C2 + 1) * 2 * t - BACK_C2)) / 2;
+ }
+ return (Math.pow(2 * t - 2, 2) * ((BACK_C2 + 1) * (t * 2 - 2) + BACK_C2) + 2) / 2;
+}
+
+const ELASTIC_C4 = (2 * Math.PI) / 3;
+const ELASTIC_C5 = (2 * Math.PI) / 4.5;
+
+function easeInElastic(t: number): number {
+ if (t === 0 || t === 1) return t;
+ return -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * ELASTIC_C4);
+}
+
+function easeOutElastic(t: number): number {
+ if (t === 0 || t === 1) return t;
+ return Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * ELASTIC_C4) + 1;
+}
+
+function easeInOutElastic(t: number): number {
+ if (t === 0 || t === 1) return t;
+ if (t < 0.5) {
+ return -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * ELASTIC_C5)) / 2;
+ }
+ return (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * ELASTIC_C5)) / 2 + 1;
+}
+
+const BOUNCE_N1 = 7.5625;
+const BOUNCE_D1 = 2.75;
+
+function easeOutBounce(t: number): number {
+ if (t < 1 / BOUNCE_D1) {
+ return BOUNCE_N1 * t * t;
+ } else if (t < 2 / BOUNCE_D1) {
+ t -= 1.5 / BOUNCE_D1;
+ return BOUNCE_N1 * t * t + 0.75;
+ } else if (t < 2.5 / BOUNCE_D1) {
+ t -= 2.25 / BOUNCE_D1;
+ return BOUNCE_N1 * t * t + 0.9375;
+ } else {
+ t -= 2.625 / BOUNCE_D1;
+ return BOUNCE_N1 * t * t + 0.984375;
+ }
+}
+
+const BEZIER_MAX_ITERATIONS = 8;
+const BEZIER_EPSILON = 1e-6;
+
+function cubicBezier(t: number, p1x: number, p1y: number, p2x: number, p2y: number): number {
+ let x = t;
+ for (let i = 0; i < BEZIER_MAX_ITERATIONS; i++) {
+ const ix = 1 - x;
+ const cx = 3 * p1x * ix * ix * x + 3 * p2x * ix * x * x + x * x * x - t;
+ if (Math.abs(cx) < BEZIER_EPSILON) break;
+ const dx = 3 * p1x * (1 - 2 * x) * (1 - x)
+ + 6 * p2x * x * (1 - x)
+ - 3 * p2x * x * x
+ + 3 * x * x;
+ if (Math.abs(dx) < BEZIER_EPSILON) break;
+ x -= cx / dx;
+ }
+ const ix = 1 - x;
+ return 3 * p1y * ix * ix * x + 3 * p2y * ix * x * x + x * x * x;
+}
+
+function step(t: number): number {
+ return t < 1 ? 0 : 1;
+}
+
+// =============================================================================
+// Public Easing Dispatcher
+// =============================================================================
+
+export function applyEasing(type: EasingType, t: number, bezier?: BezierPoints): number {
+ switch (type) {
+ case EasingType.Linear: return easeLinear(t);
+ case EasingType.EaseInQuad: return easeInQuad(t);
+ case EasingType.EaseOutQuad: return easeOutQuad(t);
+ case EasingType.EaseInOutQuad: return easeInOutQuad(t);
+ case EasingType.EaseInCubic: return easeInCubic(t);
+ case EasingType.EaseOutCubic: return easeOutCubic(t);
+ case EasingType.EaseInOutCubic: return easeInOutCubic(t);
+ case EasingType.EaseInBack: return easeInBack(t);
+ case EasingType.EaseOutBack: return easeOutBack(t);
+ case EasingType.EaseInOutBack: return easeInOutBack(t);
+ case EasingType.EaseInElastic: return easeInElastic(t);
+ case EasingType.EaseOutElastic: return easeOutElastic(t);
+ case EasingType.EaseInOutElastic: return easeInOutElastic(t);
+ case EasingType.EaseOutBounce: return easeOutBounce(t);
+ case EasingType.CubicBezier:
+ if (bezier) return cubicBezier(t, bezier.p1x, bezier.p1y, bezier.p2x, bezier.p2y);
+ return easeLinear(t);
+ case EasingType.Step: return step(t);
+ default: return easeLinear(t);
+ }
+}
+
+// =============================================================================
+// Value Tween Entry
+// =============================================================================
+
+interface ValueTweenEntry {
+ id: number;
+ from: number;
+ to: number;
+ duration: number;
+ elapsed: number;
+ delay: number;
+ easing: EasingType;
+ bezierPoints: BezierPoints | null;
+ state: TweenState;
+ loop: LoopMode;
+ loopCount: number;
+ loopsRemaining: number;
+ callback: (value: number) => void;
+ sequenceNext: number | null;
+ sequenceNextExternal: { pause(): void; resume(): void } | null;
+}
+
+// =============================================================================
+// Value Tween Manager
+// =============================================================================
+
+class ValueTweenManager {
+ private entries_ = new Map<number, ValueTweenEntry>();
+ private nextId_ = 1;
+ private cppSequences_ = new Map<number, number>();
+ private module_: ESEngineModule | null = null;
+ private registry_: CppRegistry | null = null;
+
+ init(module: ESEngineModule, registry: CppRegistry): void {
+ this.module_ = module;
+ this.registry_ = registry;
+ }
+
+ create(
+ from: number,
+ to: number,
+ duration: number,
+ callback: (value: number) => void,
+ options?: TweenOptions,
+ ): number {
+ const id = this.nextId_++;
+ this.entries_.set(id, {
+ id,
+ from,
+ to,
+ duration,
+ elapsed: 0,
+ delay: options?.delay ?? 0,
+ easing: options?.easing ?? EasingType.Linear,
+ bezierPoints: null,
+ state: TweenState.Running,
+ loop: options?.loop ?? LoopMode.None,
+ loopCount: options?.loopCount ?? 0,
+ loopsRemaining: options?.loopCount ?? 0,
+ callback,
+ sequenceNext: null,
+ sequenceNextExternal: null,
+ });
+ return id;
+ }
+
+ update(dt: number): void {
+ if (this.module_ && this.registry_) {
+ for (const [cppEntity, jsTweenId] of this.cppSequences_) {
+ const cppState = this.module_._anim_getTweenState(
+ this.registry_, cppEntity as Entity,
+ );
+ if (cppState === TweenState.Completed) {
+ this.resume(jsTweenId);
+ this.cppSequences_.delete(cppEntity);
+ }
+ }
+ }
+
+ for (const entry of this.entries_.values()) {
+ if (entry.state !== TweenState.Running) continue;
+
+ if (entry.delay > 0) {
+ entry.delay -= dt;
+ if (entry.delay > 0) continue;
+ dt = -entry.delay;
+ entry.delay = 0;
+ }
+
+ entry.elapsed += dt;
+ const t = Math.min(entry.elapsed / entry.duration, 1);
+ const easedT = applyEasing(entry.easing, t, entry.bezierPoints ?? undefined);
+ entry.callback(entry.from + (entry.to - entry.from) * easedT);
+
+ if (t >= 1) {
+ if (entry.loop !== LoopMode.None) {
+ const infinite = entry.loopCount === 0;
+ if (infinite || entry.loopsRemaining > 1) {
+ if (!infinite) entry.loopsRemaining--;
+ entry.elapsed = 0;
+ if (entry.loop === LoopMode.PingPong) {
+ const tmp = entry.from;
+ entry.from = entry.to;
+ entry.to = tmp;
+ }
+ continue;
+ }
+ }
+ entry.state = TweenState.Completed;
+ if (entry.sequenceNext !== null) {
+ this.resume(entry.sequenceNext);
+ }
+ if (entry.sequenceNextExternal) {
+ entry.sequenceNextExternal.resume();
+ }
+ }
+ }
+ }
+
+ pause(id: number): void {
+ const entry = this.entries_.get(id);
+ if (entry && entry.state === TweenState.Running) {
+ entry.state = TweenState.Paused;
+ }
+ }
+
+ resume(id: number): void {
+ const entry = this.entries_.get(id);
+ if (entry && entry.state === TweenState.Paused) {
+ entry.state = TweenState.Running;
+ }
+ }
+
+ cancel(id: number): void {
+ const entry = this.entries_.get(id);
+ if (entry) {
+ entry.state = TweenState.Cancelled;
+ }
+ }
+
+ getState(id: number): TweenState {
+ const entry = this.entries_.get(id);
+ return entry ? entry.state as TweenState : TweenState.Cancelled;
+ }
+
+ setBezier(id: number, p1x: number, p1y: number, p2x: number, p2y: number): void {
+ const entry = this.entries_.get(id);
+ if (entry) {
+ entry.bezierPoints = { p1x, p1y, p2x, p2y };
+ }
+ }
+
+ setSequenceNext(id: number, nextId: number): void {
+ const entry = this.entries_.get(id);
+ if (entry) {
+ entry.sequenceNext = nextId;
+ this.pause(nextId);
+ }
+ }
+
+ setSequenceNextExternal(id: number, external: { pause(): void; resume(): void }): void {
+ const entry = this.entries_.get(id);
+ if (entry) {
+ entry.sequenceNextExternal = external;
+ external.pause();
+ }
+ }
+
+ registerCppSequence(cppEntity: Entity, jsTweenId: number): void {
+ this.cppSequences_.set(cppEntity as number, jsTweenId);
+ this.pause(jsTweenId);
+ }
+
+ shutdown(): void {
+ this.entries_.clear();
+ this.cppSequences_.clear();
+ this.module_ = null;
+ this.registry_ = null;
+ this.nextId_ = 1;
+ }
+}
+
+export const valueTweenManager = new ValueTweenManager();
+
+// =============================================================================
+// Value Tween Handle
+// =============================================================================
+
+export class ValueTweenHandle {
+ readonly id: number;
+
+ constructor(id: number) {
+ this.id = id;
+ }
+
+ get state(): TweenState {
+ return valueTweenManager.getState(this.id);
+ }
+
+ bezier(p1x: number, p1y: number, p2x: number, p2y: number): this {
+ valueTweenManager.setBezier(this.id, p1x, p1y, p2x, p2y);
+ return this;
+ }
+
+ then(next: ValueTweenHandle): this;
+ then(next: { pause(): void; resume(): void }): this;
+ then(next: ValueTweenHandle | { pause(): void; resume(): void }): this {
+ if (next instanceof ValueTweenHandle) {
+ valueTweenManager.setSequenceNext(this.id, next.id);
+ } else {
+ valueTweenManager.setSequenceNextExternal(this.id, next);
+ }
+ return this;
+ }
+
+ pause(): void {
+ valueTweenManager.pause(this.id);
+ }
+
+ resume(): void {
+ valueTweenManager.resume(this.id);
+ }
+
+ cancel(): void {
+ valueTweenManager.cancel(this.id);
+ }
+}
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index c4a83d78b..19c3f4c2b 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -16,6 +16,11 @@ export {
type BezierPoints,
} from './Tween';
+export {
+ ValueTweenHandle,
+ applyEasing,
+} from './ValueTween';
+
export {
SpriteAnimator,
spriteAnimatorSystemUpdate,