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(animation): sine, quart, quint, expo, circ, bounce in/in-out, smoothstep and smootherstep easing curves in the engine (C++ and TypeScript, parity-tested); the Cocos tween's easing names map onto the engine's curves instead of carrying their own
yhhb17516227f11
diff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex b33da2792..3492b6ffe 100644--- a/docs/astro/src/content/docs/animation/overview.mdx+++ b/docs/astro/src/content/docs/animation/overview.mdx@@ -315,9 +315,10 @@ const animate = defineSystem([Res(Tween)], (tween) => {| `loop` | `LoopMode` | `None` | `None` / `Restart` / `PingPong`. || `loopCount` | number | `0` | Number of loops; `-1` = forever. |-`EasingType` covers `Linear`, the quad/cubic/back/elastic families-(`EaseIn*` / `EaseOut*` / `EaseInOut*`), `EaseOutBounce`, `Step`, and `CubicBezier`-— use a custom bezier with the handle's `.bezier(p1x, p1y, p2x, p2y)`.+`EasingType` covers `Linear`, the quad/cubic/quart/quint/sine/expo/circ/back/elastic+families (`EaseIn*` / `EaseOut*` / `EaseInOut*`), the bounce family (`EaseInBounce`,+`EaseOutBounce`, `EaseInOutBounce`), `Smoothstep` and `Smootherstep`, `Step`, and+`CubicBezier` — use a custom bezier with the handle's `.bezier(p1x, p1y, p2x, p2y)`.diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxindex 7138cbdf9..db7ea2d0d 100644--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx@@ -290,9 +290,10 @@ const animate = defineSystem([Res(Tween)], (tween) => {| `loop` | `LoopMode` | `None` | `None` / `Restart` / `PingPong`。 || `loopCount` | number | `0` | 循环次数;`-1` = 永远。 |-`EasingType` 覆盖 `Linear`、quad/cubic/back/elastic 系列(`EaseIn*` / `EaseOut*` /-`EaseInOut*`)、`EaseOutBounce`、`Step` 和 `CubicBezier`——自定义贝塞尔用句柄的-`.bezier(p1x, p1y, p2x, p2y)`。+`EasingType` 覆盖 `Linear`、quad/cubic/quart/quint/sine/expo/circ/back/elastic+系列(`EaseIn*` / `EaseOut*` / `EaseInOut*`)、bounce 系列(`EaseInBounce`、+`EaseOutBounce`、`EaseInOutBounce`)、`Smoothstep` 与 `Smootherstep`、`Step` 和+`CubicBezier`——自定义贝塞尔用句柄的 `.bezier(p1x, p1y, p2x, p2y)`。diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 111e8aa84..e1bffd924 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 115 public · 159 beta · 1963 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"11e3c2bb051fdd37"+"6c653a8ebb70b5bc"```## ANCHOR_AXES — const @experimental@@ -3671,19 +3671,38 @@ readonly ["texture-compression-astc", "texture-compression-bc", "texture-compres```CubicBezier = 14EaseInBack = 7+EaseInBounce = 31+EaseInCirc = 28EaseInCubic = 4EaseInElastic = 10+EaseInExpo = 25EaseInOutBack = 9+EaseInOutBounce = 32+EaseInOutCirc = 30EaseInOutCubic = 6EaseInOutElastic = 12+EaseInOutExpo = 27EaseInOutQuad = 3+EaseInOutQuart = 21+EaseInOutQuint = 24+EaseInOutSine = 18EaseInQuad = 1+EaseInQuart = 19+EaseInQuint = 22+EaseInSine = 16EaseOutBack = 8EaseOutBounce = 13+EaseOutCirc = 29EaseOutCubic = 5EaseOutElastic = 11+EaseOutExpo = 26EaseOutQuad = 2+EaseOutQuart = 20+EaseOutQuint = 23+EaseOutSine = 17Linear = 0+Smootherstep = 34+Smoothstep = 33Step = 15```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex d6834dfb4..6d9ca0f72 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 115 public · 164 beta · 1982 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"11e3c2bb051fdd37"+"6c653a8ebb70b5bc"```## ANCHOR_AXES — const @experimental@@ -3679,19 +3679,38 @@ readonly ["texture-compression-astc", "texture-compression-bc", "texture-compres```CubicBezier = 14EaseInBack = 7+EaseInBounce = 31+EaseInCirc = 28EaseInCubic = 4EaseInElastic = 10+EaseInExpo = 25EaseInOutBack = 9+EaseInOutBounce = 32+EaseInOutCirc = 30EaseInOutCubic = 6EaseInOutElastic = 12+EaseInOutExpo = 27EaseInOutQuad = 3+EaseInOutQuart = 21+EaseInOutQuint = 24+EaseInOutSine = 18EaseInQuad = 1+EaseInQuart = 19+EaseInQuint = 22+EaseInSine = 16EaseOutBack = 8EaseOutBounce = 13+EaseOutCirc = 29EaseOutCubic = 5EaseOutElastic = 11+EaseOutExpo = 26EaseOutQuad = 2+EaseOutQuart = 20+EaseOutQuint = 23+EaseOutSine = 17Linear = 0+Smootherstep = 34+Smoothstep = 33Step = 15```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex aeea5b619..cc4036be0 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -3666,19 +3666,38 @@ readonly ["texture-compression-astc", "texture-compression-bc", "texture-compres```CubicBezier = 14EaseInBack = 7+EaseInBounce = 31+EaseInCirc = 28EaseInCubic = 4EaseInElastic = 10+EaseInExpo = 25EaseInOutBack = 9+EaseInOutBounce = 32+EaseInOutCirc = 30EaseInOutCubic = 6EaseInOutElastic = 12+EaseInOutExpo = 27EaseInOutQuad = 3+EaseInOutQuart = 21+EaseInOutQuint = 24+EaseInOutSine = 18EaseInQuad = 1+EaseInQuart = 19+EaseInQuint = 22+EaseInSine = 16EaseOutBack = 8EaseOutBounce = 13+EaseOutCirc = 29EaseOutCubic = 5EaseOutElastic = 11+EaseOutExpo = 26EaseOutQuad = 2+EaseOutQuart = 20+EaseOutQuint = 23+EaseOutSine = 17Linear = 0+Smootherstep = 34+Smoothstep = 33Step = 15```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 997505e20..092df67d7 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -3666,19 +3666,38 @@ readonly ["texture-compression-astc", "texture-compression-bc", "texture-compres```CubicBezier = 14EaseInBack = 7+EaseInBounce = 31+EaseInCirc = 28EaseInCubic = 4EaseInElastic = 10+EaseInExpo = 25EaseInOutBack = 9+EaseInOutBounce = 32+EaseInOutCirc = 30EaseInOutCubic = 6EaseInOutElastic = 12+EaseInOutExpo = 27EaseInOutQuad = 3+EaseInOutQuart = 21+EaseInOutQuint = 24+EaseInOutSine = 18EaseInQuad = 1+EaseInQuart = 19+EaseInQuint = 22+EaseInSine = 16EaseOutBack = 8EaseOutBounce = 13+EaseOutCirc = 29EaseOutCubic = 5EaseOutElastic = 11+EaseOutExpo = 26EaseOutQuad = 2+EaseOutQuart = 20+EaseOutQuint = 23+EaseOutSine = 17Linear = 0+Smootherstep = 34+Smoothstep = 33Step = 15```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 12d5f414f..f85e5e646 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -3666,19 +3666,38 @@ readonly ["texture-compression-astc", "texture-compression-bc", "texture-compres```CubicBezier = 14EaseInBack = 7+EaseInBounce = 31+EaseInCirc = 28EaseInCubic = 4EaseInElastic = 10+EaseInExpo = 25EaseInOutBack = 9+EaseInOutBounce = 32+EaseInOutCirc = 30EaseInOutCubic = 6EaseInOutElastic = 12+EaseInOutExpo = 27EaseInOutQuad = 3+EaseInOutQuart = 21+EaseInOutQuint = 24+EaseInOutSine = 18EaseInQuad = 1+EaseInQuart = 19+EaseInQuint = 22+EaseInSine = 16EaseOutBack = 8EaseOutBounce = 13+EaseOutCirc = 29EaseOutCubic = 5EaseOutElastic = 11+EaseOutExpo = 26EaseOutQuad = 2+EaseOutQuart = 20+EaseOutQuint = 23+EaseOutSine = 17Linear = 0+Smootherstep = 34+Smoothstep = 33Step = 15```diff --git a/sdk/src/animation/Easing.ts b/sdk/src/animation/Easing.tsindex 72feaf02b..a78e4f1c7 100644--- a/sdk/src/animation/Easing.ts+++ b/sdk/src/animation/Easing.ts@@ -149,6 +149,50 @@ function step(t: number): number {return t < 1 ? 0 : 1;}+// Sine, quart, quint, expo, circ, bounce in/in-out, smoothstep: ports of the same-named functions in EasingFunctions.hpp.++export function easeInSine(t: number): number { return 1 - Math.cos((t * Math.PI) / 2); }+export function easeOutSine(t: number): number { return Math.sin((t * Math.PI) / 2); }+export function easeInOutSine(t: number): number { return -(Math.cos(Math.PI * t) - 1) / 2; }++export function easeInQuart(t: number): number { return t * t * t * t; }+export function easeOutQuart(t: number): number { const u = 1 - t; return 1 - u * u * u * u; }+export function easeInOutQuart(t: number): number {+ if (t < 0.5) return 8 * t * t * t * t;+ const u = -2 * t + 2;+ return 1 - (u * u * u * u) / 2;+}++export function easeInQuint(t: number): number { return t * t * t * t * t; }+export function easeOutQuint(t: number): number { const u = 1 - t; return 1 - u * u * u * u * u; }+export function easeInOutQuint(t: number): number {+ if (t < 0.5) return 16 * t * t * t * t * t;+ const u = -2 * t + 2;+ return 1 - (u * u * u * u * u) / 2;+}++export function easeInExpo(t: number): number { return t === 0 ? 0 : 2 ** (10 * t - 10); }+export function easeOutExpo(t: number): number { return t === 1 ? 1 : 1 - 2 ** (-10 * t); }+export function easeInOutExpo(t: number): number {+ if (t === 0 || t === 1) return t;+ return t < 0.5 ? 2 ** (20 * t - 10) / 2 : (2 - 2 ** (-20 * t + 10)) / 2;+}++export function easeInCirc(t: number): number { return 1 - Math.sqrt(1 - t * t); }+export function easeOutCirc(t: number): number { const u = t - 1; return Math.sqrt(1 - u * u); }+export function easeInOutCirc(t: number): number {+ if (t < 0.5) return (1 - Math.sqrt(1 - (2 * t) ** 2)) / 2;+ return (Math.sqrt(1 - (-2 * t + 2) ** 2) + 1) / 2;+}++export function easeInBounce(t: number): number { return 1 - easeOutBounce(1 - t); }+export function easeInOutBounce(t: number): number {+ return t < 0.5 ? (1 - easeOutBounce(1 - 2 * t)) / 2 : (1 + easeOutBounce(2 * t - 1)) / 2;+}++export function smoothstep(t: number): number { return t <= 0 ? 0 : t >= 1 ? 1 : t * t * (3 - 2 * t); }+export function smootherstep(t: number): number { return t <= 0 ? 0 : t >= 1 ? 1 : t * t * t * (t * (t * 6 - 15) + 10); }+// =============================================================================// Public Easing Dispatcher// =============================================================================@@ -173,6 +217,25 @@ export function applyEasing(type: EasingType, t: number, bezier?: BezierPoints):if (bezier) return cubicBezier(t, bezier.p1x, bezier.p1y, bezier.p2x, bezier.p2y);return easeLinear(t);case EasingType.Step: return step(t);+ case EasingType.EaseInSine: return easeInSine(t);+ case EasingType.EaseOutSine: return easeOutSine(t);+ case EasingType.EaseInOutSine: return easeInOutSine(t);+ case EasingType.EaseInQuart: return easeInQuart(t);+ case EasingType.EaseOutQuart: return easeOutQuart(t);+ case EasingType.EaseInOutQuart: return easeInOutQuart(t);+ case EasingType.EaseInQuint: return easeInQuint(t);+ case EasingType.EaseOutQuint: return easeOutQuint(t);+ case EasingType.EaseInOutQuint: return easeInOutQuint(t);+ case EasingType.EaseInExpo: return easeInExpo(t);+ case EasingType.EaseOutExpo: return easeOutExpo(t);+ case EasingType.EaseInOutExpo: return easeInOutExpo(t);+ case EasingType.EaseInCirc: return easeInCirc(t);+ case EasingType.EaseOutCirc: return easeOutCirc(t);+ case EasingType.EaseInOutCirc: return easeInOutCirc(t);+ case EasingType.EaseInBounce: return easeInBounce(t);+ case EasingType.EaseInOutBounce: return easeInOutBounce(t);+ case EasingType.Smoothstep: return smoothstep(t);+ case EasingType.Smootherstep: return smootherstep(t);default: return easeLinear(t);}}diff --git a/sdk/src/cocos/easing.ts b/sdk/src/cocos/easing.tsindex dee3f080f..0cbb45575 100644--- a/sdk/src/cocos/easing.ts+++ b/sdk/src/cocos/easing.ts@@ -2,108 +2,54 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file cocos/easing.ts- * @brief The easing curves a tween names: `'sineOut'`, `'backInOut'`, … and the functions behind them.+ * @brief The easing names a Cocos tween uses (`'sineOut'`, `'backInOut'`) and the `easing` functions, over the engine's curves.*- * Each curve takes progress 0..1 and returns eased progress. The families are the standard ones (Penner's), with the- * parameters Cocos uses where a curve has any (elastic's amplitude and period, back's overshoot).+ * There are no curves here: each name is an `EasingType` of the engine's animation module, and the function is the engine's+ * `applyEasing`. A tween on a Cocos object and a tween the engine runs on a component field ease the same way because they are+ * the same curve.+ *+ * Not carried: the `...OutIn` curves, which the engine has no member for. A script that names one gets a linear ease and a warning.+ * Cocos's elastic curves have their own constants; the engine's elastic is the standard one, so they differ a little in overshoot.*/-export type EasingFunction = (k: number) => number;--const PI = Math.PI;+import { EasingType, applyEasing } from '../animation/Easing';+import { log } from '../util/logger';-const quadIn: EasingFunction = (k) => k * k;-const quadOut: EasingFunction = (k) => k * (2 - k);-const quadInOut: EasingFunction = (k) => ((k *= 2) < 1 ? 0.5 * k * k : -0.5 * (--k * (k - 2) - 1));-const cubicIn: EasingFunction = (k) => k * k * k;-const cubicOut: EasingFunction = (k) => --k * k * k + 1;-const cubicInOut: EasingFunction = (k) => ((k *= 2) < 1 ? 0.5 * k * k * k : 0.5 * ((k -= 2) * k * k + 2));-const quartIn: EasingFunction = (k) => k * k * k * k;-const quartOut: EasingFunction = (k) => 1 - --k * k * k * k;-const quartInOut: EasingFunction = (k) => ((k *= 2) < 1 ? 0.5 * k * k * k * k : -0.5 * ((k -= 2) * k * k * k - 2));-const quintIn: EasingFunction = (k) => k * k * k * k * k;-const quintOut: EasingFunction = (k) => --k * k * k * k * k + 1;-const quintInOut: EasingFunction = (k) => ((k *= 2) < 1 ? 0.5 * k * k * k * k * k : 0.5 * ((k -= 2) * k * k * k * k + 2));-const sineIn: EasingFunction = (k) => (k === 1 ? 1 : 1 - Math.cos((k * PI) / 2));-const sineOut: EasingFunction = (k) => Math.sin((k * PI) / 2);-const sineInOut: EasingFunction = (k) => 0.5 * (1 - Math.cos(PI * k));-const expoIn: EasingFunction = (k) => (k === 0 ? 0 : 1024 ** (k - 1));-const expoOut: EasingFunction = (k) => (k === 1 ? 1 : 1 - 2 ** (-10 * k));-const expoInOut: EasingFunction = (k) => {- if (k === 0) return 0;- if (k === 1) return 1;- if ((k *= 2) < 1) return 0.5 * 1024 ** (k - 1);- return 0.5 * (-(2 ** (-10 * (k - 1))) + 2);-};-const circIn: EasingFunction = (k) => 1 - Math.sqrt(1 - k * k);-const circOut: EasingFunction = (k) => Math.sqrt(1 - --k * k);-const circInOut: EasingFunction = (k) => ((k *= 2) < 1 ? -0.5 * (Math.sqrt(1 - k * k) - 1) : 0.5 * (Math.sqrt(1 - (k -= 2) * k) + 1));--const elasticIn: EasingFunction = (k) => {- if (k === 0) return 0;- if (k === 1) return 1;- const a = 0.1, p = 0.4;- const s = p / 4;- return -(1 * 2 ** (10 * (k -= 1)) * Math.sin(((k - s) * 2 * PI) / p)) * (a / a);-};-const elasticOut: EasingFunction = (k) => {- if (k === 0) return 0;- if (k === 1) return 1;- const p = 0.4;- const s = p / 4;- return 2 ** (-10 * k) * Math.sin(((k - s) * 2 * PI) / p) + 1;-};-const elasticInOut: EasingFunction = (k) => {- if (k === 0) return 0;- if (k === 1) return 1;- const p = 0.4 * 1.5;- const s = p / 4;- if ((k *= 2) < 1) return -0.5 * 2 ** (10 * (k -= 1)) * Math.sin(((k - s) * 2 * PI) / p);- return 2 ** (-10 * (k -= 1)) * Math.sin(((k - s) * 2 * PI) / p) * 0.5 + 1;-};--const S = 1.70158;-const backIn: EasingFunction = (k) => (k === 1 ? 1 : k * k * ((S + 1) * k - S));-const backOut: EasingFunction = (k) => (k === 0 ? 0 : --k * k * ((S + 1) * k + S) + 1);-const backInOut: EasingFunction = (k) => {- const s = S * 1.525;- if ((k *= 2) < 1) return 0.5 * (k * k * ((s + 1) * k - s));- return 0.5 * ((k -= 2) * k * ((s + 1) * k + s) + 2);-};+export type EasingFunction = (k: number) => number;-const bounceOut: EasingFunction = (k) => {- if (k < 1 / 2.75) return 7.5625 * k * k;- if (k < 2 / 2.75) return 7.5625 * (k -= 1.5 / 2.75) * k + 0.75;- if (k < 2.5 / 2.75) return 7.5625 * (k -= 2.25 / 2.75) * k + 0.9375;- return 7.5625 * (k -= 2.625 / 2.75) * k + 0.984375;+const E = EasingType;++/** Cocos's name for each curve the engine has. */+const NAMES: Readonly<Record<string, EasingType>> = {+ linear: E.Linear, constant: E.Step, smooth: E.Smoothstep, fade: E.Smootherstep,+ quadIn: E.EaseInQuad, quadOut: E.EaseOutQuad, quadInOut: E.EaseInOutQuad,+ cubicIn: E.EaseInCubic, cubicOut: E.EaseOutCubic, cubicInOut: E.EaseInOutCubic,+ quartIn: E.EaseInQuart, quartOut: E.EaseOutQuart, quartInOut: E.EaseInOutQuart,+ quintIn: E.EaseInQuint, quintOut: E.EaseOutQuint, quintInOut: E.EaseInOutQuint,+ sineIn: E.EaseInSine, sineOut: E.EaseOutSine, sineInOut: E.EaseInOutSine,+ expoIn: E.EaseInExpo, expoOut: E.EaseOutExpo, expoInOut: E.EaseInOutExpo,+ circIn: E.EaseInCirc, circOut: E.EaseOutCirc, circInOut: E.EaseInOutCirc,+ elasticIn: E.EaseInElastic, elasticOut: E.EaseOutElastic, elasticInOut: E.EaseInOutElastic,+ backIn: E.EaseInBack, backOut: E.EaseOutBack, backInOut: E.EaseInOutBack,+ bounceIn: E.EaseInBounce, bounceOut: E.EaseOutBounce, bounceInOut: E.EaseInOutBounce,};-const bounceIn: EasingFunction = (k) => 1 - bounceOut(1 - k);-const bounceInOut: EasingFunction = (k) => (k < 0.5 ? bounceIn(k * 2) * 0.5 : bounceOut(k * 2 - 1) * 0.5 + 0.5);-/** The curve that runs the "out" half first, then the "in" half. */-const outIn = (out: EasingFunction, inn: EasingFunction): EasingFunction => (k) => (k < 0.5 ? 0.5 * out(2 * k) : 0.5 * inn(2 * k - 1) + 0.5);+export const easing: Readonly<Record<string, EasingFunction>> = Object.freeze(+ Object.fromEntries(Object.entries(NAMES).map(([name, type]) => [name, (k: number): number => applyEasing(type, k)])),+);-export const easing = {- linear: ((k) => k) as EasingFunction,- smooth: ((k) => (k <= 0 ? 0 : k >= 1 ? 1 : k * k * (3 - 2 * k))) as EasingFunction,- fade: ((k) => (k <= 0 ? 0 : k >= 1 ? 1 : k * k * k * (k * (k * 6 - 15) + 10))) as EasingFunction,- constant: ((k) => (k >= 1 ? 1 : 0)) as EasingFunction,- quadIn, quadOut, quadInOut, quadOutIn: outIn(quadOut, quadIn),- cubicIn, cubicOut, cubicInOut, cubicOutIn: outIn(cubicOut, cubicIn),- quartIn, quartOut, quartInOut, quartOutIn: outIn(quartOut, quartIn),- quintIn, quintOut, quintInOut, quintOutIn: outIn(quintOut, quintIn),- sineIn, sineOut, sineInOut, sineOutIn: outIn(sineOut, sineIn),- expoIn, expoOut, expoInOut, expoOutIn: outIn(expoOut, expoIn),- circIn, circOut, circInOut, circOutIn: outIn(circOut, circIn),- elasticIn, elasticOut, elasticInOut, elasticOutIn: outIn(elasticOut, elasticIn),- backIn, backOut, backInOut, backOutIn: outIn(backOut, backIn),- bounceIn, bounceOut, bounceInOut, bounceOutIn: outIn(bounceOut, bounceIn),-} as const;+export type EasingName = keyof typeof NAMES;-export type EasingName = keyof typeof easing;+const warned = new Set<string>();-/** A curve by name or function; an unknown name is linear, as a mistyped name is in Cocos. */+/** A curve by name or function; an unknown name is linear, with a warning once. */export function resolveEasing(e: EasingName | EasingFunction | string | undefined): EasingFunction {if (typeof e === 'function') return e;- if (typeof e === 'string' && e in easing) return easing[e as EasingName];- return easing.linear;+ if (e === undefined) return easing.linear!;+ const known = easing[e];+ if (known) return known;+ if (!warned.has(e)) {+ warned.add(e);+ log.warn('cocos', `easing "${e}" is not supported (the engine has no such curve); using linear`);+ }+ return easing.linear!;}diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 881ab8eb3..818ef1e8e 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '11e3c2bb051fdd37';+export const ABI_LAYOUT_HASH = '6c653a8ebb70b5bc';/*** One asset-valued field of a component: which field, and what kind ofdiff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex bfcd71b4f..2c23ddfef 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -103,6 +103,25 @@ export enum EasingType {EaseOutBounce = 13,CubicBezier = 14,Step = 15,+ EaseInSine = 16,+ EaseOutSine = 17,+ EaseInOutSine = 18,+ EaseInQuart = 19,+ EaseOutQuart = 20,+ EaseInOutQuart = 21,+ EaseInQuint = 22,+ EaseOutQuint = 23,+ EaseInOutQuint = 24,+ EaseInExpo = 25,+ EaseOutExpo = 26,+ EaseInOutExpo = 27,+ EaseInCirc = 28,+ EaseOutCirc = 29,+ EaseInOutCirc = 30,+ EaseInBounce = 31,+ EaseInOutBounce = 32,+ Smoothstep = 33,+ Smootherstep = 34,}/**diff --git a/sdk/tests/animation-easing-curves.test.ts b/sdk/tests/animation-easing-curves.test.tsnew file mode 100644index 000000000..2432fbef4--- /dev/null+++ b/sdk/tests/animation-easing-curves.test.ts@@ -0,0 +1,70 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The engine's easing curves: every named curve starts at 0 and ends at 1, in/out are mirrors, and a few well-known midpoints.+ *+ * The same functions exist in C++ (EasingFunctions.hpp) for tweens the engine runs itself; this pins the TypeScript side, which+ * the JS value tweens and the compatibility layer use.+ */+import { describe, expect, it } from 'vitest';+import { EasingType, applyEasing } from '../src/animation/Easing';++const CURVES: EasingType[] = Object.values(EasingType)+ .filter((v): v is EasingType => typeof v === 'number' && v !== EasingType.CubicBezier && v !== EasingType.Step);++describe('easing curves', () => {+ it('has every curve begin at 0 and end at 1', () => {+ for (const type of CURVES) {+ expect(applyEasing(type, 0), `${EasingType[type]}(0)`).toBeCloseTo(0, 6);+ expect(applyEasing(type, 1), `${EasingType[type]}(1)`).toBeCloseTo(1, 6);+ }+ });++ it('is continuous: no curve jumps between neighbouring samples', () => {+ for (const type of CURVES) {+ let prev = applyEasing(type, 0);+ for (let i = 1; i <= 200; i++) {+ const v = applyEasing(type, i / 200);+ expect(Math.abs(v - prev), `${EasingType[type]} at ${i / 200}`).toBeLessThan(0.35);+ prev = v;+ }+ }+ });++ it('mirrors in and out: out(t) = 1 - in(1 - t), for the symmetric families', () => {+ const pairs: Array<[EasingType, EasingType]> = [+ [EasingType.EaseInSine, EasingType.EaseOutSine], [EasingType.EaseInQuart, EasingType.EaseOutQuart],+ [EasingType.EaseInQuint, EasingType.EaseOutQuint], [EasingType.EaseInExpo, EasingType.EaseOutExpo],+ [EasingType.EaseInCirc, EasingType.EaseOutCirc], [EasingType.EaseInBounce, EasingType.EaseOutBounce],+ ];+ for (const [inn, out] of pairs) {+ for (const t of [0.1, 0.3, 0.5, 0.8]) {+ expect(applyEasing(out, t), `${EasingType[out]}(${t})`).toBeCloseTo(1 - applyEasing(inn, 1 - t), 4);+ }+ }+ });++ it('is half way at half for the symmetric in-out curves', () => {+ for (const type of [EasingType.EaseInOutSine, EasingType.EaseInOutQuart, EasingType.EaseInOutQuint, EasingType.EaseInOutExpo,+ EasingType.EaseInOutCirc, EasingType.EaseInOutBounce, EasingType.Smoothstep, EasingType.Smootherstep]) {+ expect(applyEasing(type, 0.5), EasingType[type]).toBeCloseTo(0.5, 6);+ }+ });++ it('has the well-known values', () => {+ expect(applyEasing(EasingType.EaseOutSine, 0.5)).toBeCloseTo(Math.SQRT1_2, 6);+ expect(applyEasing(EasingType.EaseInQuart, 0.5)).toBeCloseTo(0.0625, 6);+ expect(applyEasing(EasingType.EaseInQuint, 0.5)).toBeCloseTo(0.03125, 6);+ expect(applyEasing(EasingType.EaseOutCirc, 0.5)).toBeCloseTo(Math.sqrt(0.75), 6);+ expect(applyEasing(EasingType.Smoothstep, 0.25)).toBeCloseTo(0.15625, 6);+ expect(applyEasing(EasingType.Smootherstep, 0.25)).toBeCloseTo(0.103515625, 6);+ });++ it('keeps the numbers the curves already had, since scenes and the ABI store them', () => {+ expect(EasingType.Linear).toBe(0);+ expect(EasingType.EaseInQuad).toBe(1);+ expect(EasingType.EaseOutBounce).toBe(13);+ expect(EasingType.CubicBezier).toBe(14);+ expect(EasingType.Step).toBe(15);+ });+});diff --git a/sdk/tests/animation-easing-parity-wasm.test.ts b/sdk/tests/animation-easing-parity-wasm.test.tsnew file mode 100644index 000000000..729dc3850--- /dev/null+++ b/sdk/tests/animation-easing-parity-wasm.test.ts@@ -0,0 +1,37 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Every easing curve gives the same answer in C++ (the tween the engine runs itself) and in TypeScript (the value tween).+ *+ * The two implementations are ports of each other and share one enum; a curve added to one and not the other is a tween that+ * eases differently depending on which kind of field it animates. This runs the same tween both ways at several times and compares.+ */+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';+import { World } from '../src/ecs/world';+import { Transform } from '../src/ecs/component';+import { TweenAPI, TweenTarget } from '../src/animation/Tween';+import { EasingType, applyEasing } from '../src/animation/Easing';+import type { CppRegistry, ESEngineModule } from '../src/wasm';+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';++const CURVES: EasingType[] = Object.values(EasingType)+ .filter((v): v is EasingType => typeof v === 'number' && v !== EasingType.CubicBezier);++describe.skipIf(!HAS_WASM)('easing parity between C++ and TypeScript', () => {+ let engine: ESEngineModule, registry: CppRegistry, world: World;+ beforeAll(async () => { engine = await loadWasmModule(); });+ beforeEach(() => { registry = new engine.Registry(); world = new World(); world.connectCpp(registry, engine); });+ afterEach(() => { for (const e of world.getAllEntities()) world.despawn(e); world.disconnectCpp(); registry.delete(); });++ it.each(CURVES.map((c) => [EasingType[c], c] as const))('%s', (_name, type) => {+ for (const t of [0.1, 0.25, 0.5, 0.75, 0.9]) {+ const api = new TweenAPI(engine, registry);+ const entity = world.spawn();+ world.insert(entity, Transform);+ api.to(entity, TweenTarget.PositionX, 0, 100, 1, { easing: type });+ api.update(t);+ const native = world.get(entity, Transform).position.x;+ expect(native, `${EasingType[type]} at ${t}`).toBeCloseTo(100 * applyEasing(type, t), 2);+ }+ });+});diff --git a/src/esengine/animation/EasingFunctions.hpp b/src/esengine/animation/EasingFunctions.hppindex 65168f9c9..d317aee31 100644--- a/src/esengine/animation/EasingFunctions.hpp+++ b/src/esengine/animation/EasingFunctions.hpp@@ -108,6 +108,46 @@ inline f32 easeOutBounce(f32 t) {}}+// Sine, quart, quint, expo and circ: the standard (Penner) curves. Each In/Out/InOut triple starts at 0 and ends at 1.++inline f32 easeInSine(f32 t) { return 1.0f - std::cos((t * ANIM_PI) / 2.0f); }+inline f32 easeOutSine(f32 t) { return std::sin((t * ANIM_PI) / 2.0f); }+inline f32 easeInOutSine(f32 t) { return -(std::cos(ANIM_PI * t) - 1.0f) / 2.0f; }++inline f32 easeInQuart(f32 t) { return t * t * t * t; }+inline f32 easeOutQuart(f32 t) { f32 u = 1.0f - t; return 1.0f - u * u * u * u; }+inline f32 easeInOutQuart(f32 t) {+ if (t < 0.5f) return 8.0f * t * t * t * t;+ f32 u = -2.0f * t + 2.0f;+ return 1.0f - u * u * u * u / 2.0f;+}++inline f32 easeInQuint(f32 t) { return t * t * t * t * t; }+inline f32 easeOutQuint(f32 t) { f32 u = 1.0f - t; return 1.0f - u * u * u * u * u; }+inline f32 easeInOutQuint(f32 t) {+ if (t < 0.5f) return 16.0f * t * t * t * t * t;+ f32 u = -2.0f * t + 2.0f;+ return 1.0f - u * u * u * u * u / 2.0f;+}++inline f32 easeInExpo(f32 t) { return t == 0.0f ? 0.0f : std::pow(2.0f, 10.0f * t - 10.0f); }+inline f32 easeOutExpo(f32 t) { return t == 1.0f ? 1.0f : 1.0f - std::pow(2.0f, -10.0f * t); }+inline f32 easeInOutExpo(f32 t) {+ if (t == 0.0f || t == 1.0f) return t;+ return t < 0.5f ? std::pow(2.0f, 20.0f * t - 10.0f) / 2.0f : (2.0f - std::pow(2.0f, -20.0f * t + 10.0f)) / 2.0f;+}++inline f32 easeInCirc(f32 t) { return 1.0f - std::sqrt(1.0f - t * t); }+inline f32 easeOutCirc(f32 t) { f32 u = t - 1.0f; return std::sqrt(1.0f - u * u); }+inline f32 easeInOutCirc(f32 t) {+ if (t < 0.5f) return (1.0f - std::sqrt(1.0f - std::pow(2.0f * t, 2.0f))) / 2.0f;+ return (std::sqrt(1.0f - std::pow(-2.0f * t + 2.0f, 2.0f)) + 1.0f) / 2.0f;+}++// Smoothstep is 3t^2 - 2t^3; smootherstep is 6t^5 - 15t^4 + 10t^3 (zero first AND second derivative at both ends).+inline f32 smoothstep(f32 t) { return t <= 0.0f ? 0.0f : t >= 1.0f ? 1.0f : t * t * (3.0f - 2.0f * t); }+inline f32 smootherstep(f32 t) { return t <= 0.0f ? 0.0f : t >= 1.0f ? 1.0f : t * t * t * (t * (t * 6.0f - 15.0f) + 10.0f); }+inline f32 cubicBezier(f32 t, f32 p1x, f32 p1y, f32 p2x, f32 p2y) {constexpr i32 MAX_ITERATIONS = 8;constexpr f32 EPSILON = 1e-6f;@@ -135,6 +175,11 @@ inline f32 cubicBezier(f32 t, f32 p1x, f32 p1y, f32 p2x, f32 p2y) {+ x * x * x;}+inline f32 easeInBounce(f32 t) { return 1.0f - easeOutBounce(1.0f - t); }+inline f32 easeInOutBounce(f32 t) {+ return t < 0.5f ? (1.0f - easeOutBounce(1.0f - 2.0f * t)) / 2.0f : (1.0f + easeOutBounce(2.0f * t - 1.0f)) / 2.0f;+}+inline f32 step(f32 t) {return t < 1.0f ? 0.0f : 1.0f;}@@ -158,6 +203,25 @@ inline EasingFn getEasingFunction(EasingType type) {case EasingType::EaseInOutElastic: return easeInOutElastic;case EasingType::EaseOutBounce: return easeOutBounce;case EasingType::Step: return step;+ case EasingType::EaseInSine: return easeInSine;+ case EasingType::EaseOutSine: return easeOutSine;+ case EasingType::EaseInOutSine: return easeInOutSine;+ case EasingType::EaseInQuart: return easeInQuart;+ case EasingType::EaseOutQuart: return easeOutQuart;+ case EasingType::EaseInOutQuart: return easeInOutQuart;+ case EasingType::EaseInQuint: return easeInQuint;+ case EasingType::EaseOutQuint: return easeOutQuint;+ case EasingType::EaseInOutQuint: return easeInOutQuint;+ case EasingType::EaseInExpo: return easeInExpo;+ case EasingType::EaseOutExpo: return easeOutExpo;+ case EasingType::EaseInOutExpo: return easeInOutExpo;+ case EasingType::EaseInCirc: return easeInCirc;+ case EasingType::EaseOutCirc: return easeOutCirc;+ case EasingType::EaseInOutCirc: return easeInOutCirc;+ case EasingType::EaseInBounce: return easeInBounce;+ case EasingType::EaseInOutBounce: return easeInOutBounce;+ case EasingType::Smoothstep: return smoothstep;+ case EasingType::Smootherstep: return smootherstep;default: return easeLinear;}}diff --git a/src/esengine/animation/TweenData.hpp b/src/esengine/animation/TweenData.hppindex e7e957f97..e5c237ef3 100644--- a/src/esengine/animation/TweenData.hpp+++ b/src/esengine/animation/TweenData.hpp@@ -24,7 +24,26 @@ enum class EasingType : u8 {EaseInOutElastic,EaseOutBounce,CubicBezier,- Step+ Step,+ EaseInSine,+ EaseOutSine,+ EaseInOutSine,+ EaseInQuart,+ EaseOutQuart,+ EaseInOutQuart,+ EaseInQuint,+ EaseOutQuint,+ EaseInOutQuint,+ EaseInExpo,+ EaseOutExpo,+ EaseInOutExpo,+ EaseInCirc,+ EaseOutCirc,+ EaseInOutCirc,+ EaseInBounce,+ EaseInOutBounce,+ Smoothstep,+ Smootherstep};ES_ENUM(stability=experimental)diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 165541bab..e363d646f 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -154,7 +154,26 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {.value("EaseInOutElastic", esengine::animation::EasingType::EaseInOutElastic).value("EaseOutBounce", esengine::animation::EasingType::EaseOutBounce).value("CubicBezier", esengine::animation::EasingType::CubicBezier)- .value("Step", esengine::animation::EasingType::Step);+ .value("Step", esengine::animation::EasingType::Step)+ .value("EaseInSine", esengine::animation::EasingType::EaseInSine)+ .value("EaseOutSine", esengine::animation::EasingType::EaseOutSine)+ .value("EaseInOutSine", esengine::animation::EasingType::EaseInOutSine)+ .value("EaseInQuart", esengine::animation::EasingType::EaseInQuart)+ .value("EaseOutQuart", esengine::animation::EasingType::EaseOutQuart)+ .value("EaseInOutQuart", esengine::animation::EasingType::EaseInOutQuart)+ .value("EaseInQuint", esengine::animation::EasingType::EaseInQuint)+ .value("EaseOutQuint", esengine::animation::EasingType::EaseOutQuint)+ .value("EaseInOutQuint", esengine::animation::EasingType::EaseInOutQuint)+ .value("EaseInExpo", esengine::animation::EasingType::EaseInExpo)+ .value("EaseOutExpo", esengine::animation::EasingType::EaseOutExpo)+ .value("EaseInOutExpo", esengine::animation::EasingType::EaseInOutExpo)+ .value("EaseInCirc", esengine::animation::EasingType::EaseInCirc)+ .value("EaseOutCirc", esengine::animation::EasingType::EaseOutCirc)+ .value("EaseInOutCirc", esengine::animation::EasingType::EaseInOutCirc)+ .value("EaseInBounce", esengine::animation::EasingType::EaseInBounce)+ .value("EaseInOutBounce", esengine::animation::EasingType::EaseInOutBounce)+ .value("Smoothstep", esengine::animation::EasingType::Smoothstep)+ .value("Smootherstep", esengine::animation::EasingType::Smootherstep);enum_<esengine::ecs::EmitterShape>("EmitterShape").value("Point", esengine::ecs::EmitterShape::Point)@@ -4165,7 +4184,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "11e3c2bb051fdd37";+static const char* kEsAbiLayoutHash = "6c653a8ebb70b5bc";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);