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(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.mdx
index 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)`.
![Every EasingType plotted as a curve from 0 to 1](@/assets/guides/tween-easings.svg)
diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx
index 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)`。
![每种 EasingType 从 0 到 1 的曲线](@/assets/guides/tween-easings.svg)
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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 = 14
EaseInBack = 7
+EaseInBounce = 31
+EaseInCirc = 28
EaseInCubic = 4
EaseInElastic = 10
+EaseInExpo = 25
EaseInOutBack = 9
+EaseInOutBounce = 32
+EaseInOutCirc = 30
EaseInOutCubic = 6
EaseInOutElastic = 12
+EaseInOutExpo = 27
EaseInOutQuad = 3
+EaseInOutQuart = 21
+EaseInOutQuint = 24
+EaseInOutSine = 18
EaseInQuad = 1
+EaseInQuart = 19
+EaseInQuint = 22
+EaseInSine = 16
EaseOutBack = 8
EaseOutBounce = 13
+EaseOutCirc = 29
EaseOutCubic = 5
EaseOutElastic = 11
+EaseOutExpo = 26
EaseOutQuad = 2
+EaseOutQuart = 20
+EaseOutQuint = 23
+EaseOutSine = 17
Linear = 0
+Smootherstep = 34
+Smoothstep = 33
Step = 15
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 = 14
EaseInBack = 7
+EaseInBounce = 31
+EaseInCirc = 28
EaseInCubic = 4
EaseInElastic = 10
+EaseInExpo = 25
EaseInOutBack = 9
+EaseInOutBounce = 32
+EaseInOutCirc = 30
EaseInOutCubic = 6
EaseInOutElastic = 12
+EaseInOutExpo = 27
EaseInOutQuad = 3
+EaseInOutQuart = 21
+EaseInOutQuint = 24
+EaseInOutSine = 18
EaseInQuad = 1
+EaseInQuart = 19
+EaseInQuint = 22
+EaseInSine = 16
EaseOutBack = 8
EaseOutBounce = 13
+EaseOutCirc = 29
EaseOutCubic = 5
EaseOutElastic = 11
+EaseOutExpo = 26
EaseOutQuad = 2
+EaseOutQuart = 20
+EaseOutQuint = 23
+EaseOutSine = 17
Linear = 0
+Smootherstep = 34
+Smoothstep = 33
Step = 15
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 = 14
EaseInBack = 7
+EaseInBounce = 31
+EaseInCirc = 28
EaseInCubic = 4
EaseInElastic = 10
+EaseInExpo = 25
EaseInOutBack = 9
+EaseInOutBounce = 32
+EaseInOutCirc = 30
EaseInOutCubic = 6
EaseInOutElastic = 12
+EaseInOutExpo = 27
EaseInOutQuad = 3
+EaseInOutQuart = 21
+EaseInOutQuint = 24
+EaseInOutSine = 18
EaseInQuad = 1
+EaseInQuart = 19
+EaseInQuint = 22
+EaseInSine = 16
EaseOutBack = 8
EaseOutBounce = 13
+EaseOutCirc = 29
EaseOutCubic = 5
EaseOutElastic = 11
+EaseOutExpo = 26
EaseOutQuad = 2
+EaseOutQuart = 20
+EaseOutQuint = 23
+EaseOutSine = 17
Linear = 0
+Smootherstep = 34
+Smoothstep = 33
Step = 15
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 = 14
EaseInBack = 7
+EaseInBounce = 31
+EaseInCirc = 28
EaseInCubic = 4
EaseInElastic = 10
+EaseInExpo = 25
EaseInOutBack = 9
+EaseInOutBounce = 32
+EaseInOutCirc = 30
EaseInOutCubic = 6
EaseInOutElastic = 12
+EaseInOutExpo = 27
EaseInOutQuad = 3
+EaseInOutQuart = 21
+EaseInOutQuint = 24
+EaseInOutSine = 18
EaseInQuad = 1
+EaseInQuart = 19
+EaseInQuint = 22
+EaseInSine = 16
EaseOutBack = 8
EaseOutBounce = 13
+EaseOutCirc = 29
EaseOutCubic = 5
EaseOutElastic = 11
+EaseOutExpo = 26
EaseOutQuad = 2
+EaseOutQuart = 20
+EaseOutQuint = 23
+EaseOutSine = 17
Linear = 0
+Smootherstep = 34
+Smoothstep = 33
Step = 15
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 = 14
EaseInBack = 7
+EaseInBounce = 31
+EaseInCirc = 28
EaseInCubic = 4
EaseInElastic = 10
+EaseInExpo = 25
EaseInOutBack = 9
+EaseInOutBounce = 32
+EaseInOutCirc = 30
EaseInOutCubic = 6
EaseInOutElastic = 12
+EaseInOutExpo = 27
EaseInOutQuad = 3
+EaseInOutQuart = 21
+EaseInOutQuint = 24
+EaseInOutSine = 18
EaseInQuad = 1
+EaseInQuart = 19
+EaseInQuint = 22
+EaseInSine = 16
EaseOutBack = 8
EaseOutBounce = 13
+EaseOutCirc = 29
EaseOutCubic = 5
EaseOutElastic = 11
+EaseOutExpo = 26
EaseOutQuad = 2
+EaseOutQuart = 20
+EaseOutQuint = 23
+EaseOutSine = 17
Linear = 0
+Smootherstep = 34
+Smoothstep = 33
Step = 15
```
diff --git a/sdk/src/animation/Easing.ts b/sdk/src/animation/Easing.ts
index 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.ts
index 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.ts
index 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 of
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.hpp
index 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.hpp
index 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.cpp
index 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);