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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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,