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.

refactor(animation): split shared tween types/easing into own modules

esenginefab588a0aee7
diff --git a/sdk/src/animation/Easing.ts b/sdk/src/animation/Easing.ts
new file mode 100644
index 000000000..4afc7be4b
--- /dev/null
+++ b/sdk/src/animation/Easing.ts
@@ -0,0 +1,185 @@
+/**
+ * @file Easing.ts
+ * @brief Pure easing math — 1:1 port of C++ EasingFunctions.hpp
+ *
+ * The EasingType enum values are WASM boundary contract — they must stay
+ * in lock-step with src/esengine/animation/TweenData.hpp::EasingType.
+ */
+
+// =============================================================================
+// EasingType (wire protocol — 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 interface BezierPoints {
+ p1x: number;
+ p1y: number;
+ p2x: number;
+ p2y: number;
+}
+
+// =============================================================================
+// Easing Functions
+// =============================================================================
+
+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);
+ }
+}
diff --git a/sdk/src/animation/Tween.ts b/sdk/src/animation/Tween.ts
index 2cca024ae..453c67d70 100644
--- a/sdk/src/animation/Tween.ts
+++ b/sdk/src/animation/Tween.ts
@@ -5,18 +5,14 @@
import type { Entity } from '../types';
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';
+import { EasingType } from './Easing';
+import { LoopMode, TweenState, type TweenOptions } from './TweenTypes';
+import { valueTweenManager, ValueTweenHandle } from './ValueTween';
+
+// Re-export so consumers can reach shared types via the Tween entry point
+export { EasingType, type BezierPoints } from './Easing';
+export { TweenState, LoopMode, type TweenOptions } from './TweenTypes';
+export { ValueTweenHandle } from './ValueTween';
// =============================================================================
// Tween Target (wire protocol — must stay in lock-step with
diff --git a/sdk/src/animation/TweenGroup.ts b/sdk/src/animation/TweenGroup.ts
index df90bd0ac..dcacdd019 100644
--- a/sdk/src/animation/TweenGroup.ts
+++ b/sdk/src/animation/TweenGroup.ts
@@ -3,8 +3,8 @@
* @brief Parallel and sequential tween composition utilities
*/
-import { TweenState, valueTweenManager, ValueTweenHandle } from './ValueTween';
-import type { TweenOptions } from './ValueTween';
+import { TweenState } from './TweenTypes';
+import { valueTweenManager, ValueTweenHandle } from './ValueTween';
// =============================================================================
// Completable - common interface for things that finish
diff --git a/sdk/src/animation/TweenTypes.ts b/sdk/src/animation/TweenTypes.ts
new file mode 100644
index 000000000..3140a51c7
--- /dev/null
+++ b/sdk/src/animation/TweenTypes.ts
@@ -0,0 +1,33 @@
+/**
+ * @file TweenTypes.ts
+ * @brief Shared tween enums/types — WASM boundary contract
+ *
+ * TweenState and LoopMode numeric values must match
+ * src/esengine/animation/TweenData.hpp.
+ */
+
+import type { EasingType } from './Easing';
+
+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;
+}
diff --git a/sdk/src/animation/ValueTween.ts b/sdk/src/animation/ValueTween.ts
index 5aaca455b..a90d0905b 100644
--- a/sdk/src/animation/ValueTween.ts
+++ b/sdk/src/animation/ValueTween.ts
@@ -1,212 +1,12 @@
/**
* @file ValueTween.ts
- * @brief JS-side value tweening with easing functions ported from C++
+ * @brief JS-side value tweening (fallback for fields not covered by C++ TweenTarget)
*/
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);
- }
-}
+import { applyEasing, EasingType, type BezierPoints } from './Easing';
+import { LoopMode, TweenState, type TweenOptions } from './TweenTypes';
// =============================================================================
// Value Tween Entry
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index 0ce0f2186..70bc07985 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -4,21 +4,27 @@
*/
export {
- Tween,
- TweenHandle,
EasingType,
- TweenTarget,
+ applyEasing,
+ type BezierPoints,
+} from './Easing';
+
+export {
TweenState,
LoopMode,
+ type TweenOptions,
+} from './TweenTypes';
+
+export {
+ Tween,
+ TweenHandle,
+ TweenTarget,
initTweenAPI,
shutdownTweenAPI,
- type TweenOptions,
- type BezierPoints,
} from './Tween';
export {
ValueTweenHandle,
- applyEasing,
} from './ValueTween';
export {
diff --git a/sdk/tests/tween-group.test.ts b/sdk/tests/tween-group.test.ts
index bee3e706a..5e1458ac5 100644
--- a/sdk/tests/tween-group.test.ts
+++ b/sdk/tests/tween-group.test.ts
@@ -1,6 +1,6 @@
import { describe, it, expect, vi } from 'vitest';
import { TweenGroup, TweenSequence, TweenCompose, tweenCompositionManager } from '../src/animation/TweenGroup';
-import { TweenState } from '../src/animation/ValueTween';
+import { TweenState } from '../src/animation/TweenTypes';
function mockTween(doneAfter: number) {
let elapsed = 0;