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.

examples(tween-animation): rebuild as interactive tween showcase

yhh56ede6becf6b
diff --git a/examples/tween-animation/README.md b/examples/tween-animation/README.md
new file mode 100644
index 000000000..1bf9095a8
--- /dev/null
+++ b/examples/tween-animation/README.md
@@ -0,0 +1,64 @@
+# Tween Animation
+
+A tour of the engine's built-in **tween** system — the `Tween` resource and its
+`to()` / `sequence()` / `parallel()` / `.bezier()` API, plus the 16 easing
+curves. Three things run at once:
+
+- **Easing gallery** (left) — twelve dots race the same track, each with a
+ different easing, looping back and forth. Because they start together and ease
+ differently, they visibly spread apart and regroup — the quickest way to *see*
+ what each curve does.
+- **Hero** (upper right) — a square running an endless `sequence()`: move → spin
+ + colour → move → spin + colour. Each spin/colour pair is grouped with
+ `parallel()` so they play together.
+- **Comet** (lower right) — click anywhere and it tweens to the cursor with an
+ overshooting ease and an elastic size pop. Click again mid-flight to retarget.
+
+## Controls
+
+| Input | Action |
+| ----------- | -------------------------------------------------- |
+| Left-click | Fling the comet to the cursor (retargets in-flight) |
+
+Everything else runs on its own.
+
+## The easing gallery, top to bottom
+
+`Linear`, `EaseInQuad`, `EaseOutQuad`, `EaseInOutQuad`, `EaseInCubic`,
+`EaseOutCubic`, `EaseInOutCubic`, `EaseOutBack`, `EaseInOutBack`,
+`EaseOutElastic`, `EaseOutBounce`, `CubicBezier` (a custom curve set with
+`TweenHandle.bezier()`).
+
+## How it works
+
+Tweens are driven by the built-in `TweenSystem` (registered by the
+`AnimationPlugin`); a system only has to *start* them via the `Tween` resource,
+and the C++ fast-path writes `Transform` / `Sprite` every frame — there is no
+per-frame lerp code in this example.
+
+- **Starting a tween** — `tween.to(entity, TweenTarget.PositionX, from, to,
+ seconds, { easing, loop })`. `TweenTarget` covers position, scale, rotation,
+ colour, size and camera ortho-size.
+- **Looping** — `LoopMode.PingPong` (reverse each lap) or `LoopMode.Restart`.
+- **Composition** — `tween.sequence([() => ..., () => ...])` runs factories one
+ after another (each starts when the previous finishes); `tween.parallel([...])`
+ runs tweens together. Both report completion via `.onComplete()`; the hero
+ re-arms itself there to loop forever. See `src/systems/setup.ts`.
+- **Custom curves** — `tween.to(...).bezier(p1x, p1y, p2x, p2y)` for a cubic
+ bezier easing.
+- **Retargeting** — `tween.cancelAll(entity)` stops an entity's tweens so a new
+ one can start from its live position. See `src/systems/comet.ts`.
+
+## Files
+
+```
+assets/scenes/
+ main.esscene # camera, 12 rail+dot rows, the hero, the comet
+src/
+ main.ts # registers the setup + comet systems
+ config.ts # easing list, track, hero/comet tuning
+ components.ts # GalleryDot (easing index), Hero + Comet tags
+ systems/
+ setup.ts # starts the gallery race + the looping hero sequence
+ comet.ts # click → tween the comet to the cursor
+```
diff --git a/examples/tween-animation/assets/scenes/main.esscene b/examples/tween-animation/assets/scenes/main.esscene
index c8e1cad65..3f75b9e22 100644
--- a/examples/tween-animation/assets/scenes/main.esscene
+++ b/examples/tween-animation/assets/scenes/main.esscene
@@ -11,14 +11,18 @@
{
"type": "Transform",
"data": {
- "position": { "x": 0, "y": 0, "z": 10 }
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
}
},
{
"type": "Camera",
"data": {
"projectionType": 1,
- "orthoSize": 300,
+ "orthoSize": 360,
"isActive": true,
"priority": 0
}
@@ -27,110 +31,992 @@
"visible": true
},
{
- "id": 1,
- "name": "EasingLinear",
+ "id": 100,
+ "name": "Rail_0",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": 175, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 30, "y": 30 }, "color": { "r": 0.93, "g": 0.17, "b": 0.17, "a": 1 } } },
- { "type": "EasingDemo", "data": {} }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": 300,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
],
"visible": true
},
{
- "id": 2,
- "name": "EasingInQuad",
+ "id": 200,
+ "name": "Dot_0",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": 105, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 30, "y": 30 }, "color": { "r": 0.93, "g": 0.93, "b": 0.17, "a": 1 } } },
- { "type": "EasingDemo", "data": { "easingIndex": 1 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": 300,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 1,
+ "g": 0.28,
+ "b": 0.28,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 0
+ }
+ }
],
"visible": true
},
{
- "id": 3,
- "name": "EasingOutQuad",
+ "id": 101,
+ "name": "Rail_1",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": 35, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 30, "y": 30 }, "color": { "r": 0.17, "g": 0.93, "b": 0.17, "a": 1 } } },
- { "type": "EasingDemo", "data": { "easingIndex": 2 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": 248,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
],
"visible": true
},
{
- "id": 4,
- "name": "EasingInOutQuad",
+ "id": 201,
+ "name": "Dot_1",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": -35, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 30, "y": 30 }, "color": { "r": 0.17, "g": 0.93, "b": 0.93, "a": 1 } } },
- { "type": "EasingDemo", "data": { "easingIndex": 3 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": 248,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 1,
+ "g": 0.579,
+ "b": 0.28,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 1
+ }
+ }
],
"visible": true
},
{
- "id": 5,
- "name": "EasingInCubic",
+ "id": 102,
+ "name": "Rail_2",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": -105, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 30, "y": 30 }, "color": { "r": 0.17, "g": 0.17, "b": 0.93, "a": 1 } } },
- { "type": "EasingDemo", "data": { "easingIndex": 4 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": 196,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
],
"visible": true
},
{
- "id": 6,
- "name": "EasingOutBounce",
+ "id": 202,
+ "name": "Dot_2",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": -175, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 30, "y": 30 }, "color": { "r": 0.93, "g": 0.17, "b": 0.93, "a": 1 } } },
- { "type": "EasingDemo", "data": { "easingIndex": 5 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": 196,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 1,
+ "g": 0.878,
+ "b": 0.28,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 2
+ }
+ }
],
"visible": true
},
{
- "id": 7,
- "name": "ScaleDemo",
+ "id": 103,
+ "name": "Rail_3",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": 0, "y": -200, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 50, "y": 50 } } },
- { "type": "ScaleDemo", "data": {} }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": 144,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
],
"visible": true
},
{
- "id": 8,
- "name": "RotationDemo",
+ "id": 203,
+ "name": "Dot_3",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": 250, "y": -200, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 40, "y": 40 }, "color": { "r": 0.5, "g": 1, "b": 0.8, "a": 1 } } },
- { "type": "RotationDemo", "data": {} }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": 144,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.824,
+ "g": 1,
+ "b": 0.28,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 3
+ }
+ }
],
"visible": true
},
{
- "id": 9,
- "name": "ColorDemo",
+ "id": 104,
+ "name": "Rail_4",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": -250, "y": -200, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 40, "y": 40 }, "color": { "r": 1, "g": 0, "b": 0, "a": 1 } } },
- { "type": "ColorDemo", "data": {} }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": 92,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 204,
+ "name": "Dot_4",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": 92,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.525,
+ "g": 1,
+ "b": 0.28,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 4
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 105,
+ "name": "Rail_5",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": 40,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 205,
+ "name": "Dot_5",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": 40,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.28,
+ "g": 1,
+ "b": 0.334,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 5
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 106,
+ "name": "Rail_6",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": -12,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 206,
+ "name": "Dot_6",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": -12,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.28,
+ "g": 1,
+ "b": 0.633,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 6
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 107,
+ "name": "Rail_7",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": -64,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 207,
+ "name": "Dot_7",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": -64,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.28,
+ "g": 1,
+ "b": 0.932,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 7
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 108,
+ "name": "Rail_8",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": -116,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 208,
+ "name": "Dot_8",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": -116,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.28,
+ "g": 0.77,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 8
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 109,
+ "name": "Rail_9",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": -168,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 209,
+ "name": "Dot_9",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": -168,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.28,
+ "g": 0.471,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 9
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 110,
+ "name": "Rail_10",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": -220,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 210,
+ "name": "Dot_10",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": -220,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.388,
+ "g": 0.28,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 10
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 111,
+ "name": "Rail_11",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -370,
+ "y": -272,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 500,
+ "y": 3
+ },
+ "color": {
+ "r": 0.24,
+ "g": 0.25,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 211,
+ "name": "Dot_11",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -620,
+ "y": -272,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "color": {
+ "r": 0.687,
+ "g": 0.28,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "GalleryDot",
+ "data": {
+ "index": 11
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 300,
+ "name": "Hero",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": 175,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 44,
+ "y": 44
+ },
+ "color": {
+ "r": 0.35,
+ "g": 0.7,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 1
+ }
+ },
+ {
+ "type": "Hero",
+ "data": {}
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 301,
+ "name": "Comet",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 300,
+ "y": -175,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 30,
+ "y": 30
+ },
+ "color": {
+ "r": 1,
+ "g": 0.85,
+ "b": 0.35,
+ "a": 1
+ },
+ "layer": 2
+ }
+ },
+ {
+ "type": "Comet",
+ "data": {}
+ }
],
"visible": true
}
diff --git a/examples/tween-animation/project.esproject b/examples/tween-animation/project.esproject
index d47a786b0..230a56563 100644
--- a/examples/tween-animation/project.esproject
+++ b/examples/tween-animation/project.esproject
@@ -1,13 +1,13 @@
{
"formatVersion": "1",
"name": "Tween Animation",
- "description": "Ease positions, scales and colors over time with the tween system.",
+ "description": "A tour of the built-in tween system: an easing gallery, a sequence + parallel choreography, and click-to-fling interaction.",
"tag": "Animation",
- "version": "0.1.0",
+ "version": "0.2.0",
"defaultScene": "assets/scenes/main.esscene",
"designResolution": {
- "width": 800,
- "height": 600
+ "width": 1280,
+ "height": 720
},
"spineVersion": "none"
}
diff --git a/examples/tween-animation/src/components.ts b/examples/tween-animation/src/components.ts
index 3acd13721..1849c4172 100644
--- a/examples/tween-animation/src/components.ts
+++ b/examples/tween-animation/src/components.ts
@@ -1,17 +1,13 @@
-import { defineComponent } from 'esengine';
+import { defineComponent, defineTag } from 'esengine';
-export const EasingDemo = defineComponent('EasingDemo', {
- easingIndex: 0,
+// One racing dot in the easing gallery. `index` selects its curve from
+// EASINGS in config.ts (the scene assigns one index per row).
+export const GalleryDot = defineComponent('GalleryDot', {
+ index: 0,
});
-export const ScaleDemo = defineComponent('ScaleDemo', {
- dummy: 0,
-});
-
-export const RotationDemo = defineComponent('RotationDemo', {
- dummy: 0,
-});
+// The hero that runs the looping sequence + parallel choreography.
+export const Hero = defineTag('Hero');
-export const ColorDemo = defineComponent('ColorDemo', {
- dummy: 0,
-});
+// The comet that tweens to wherever you click.
+export const Comet = defineTag('Comet');
diff --git a/examples/tween-animation/src/config.ts b/examples/tween-animation/src/config.ts
new file mode 100644
index 000000000..9b3cb6b3f
--- /dev/null
+++ b/examples/tween-animation/src/config.ts
@@ -0,0 +1,42 @@
+import { EasingType } from 'esengine';
+
+// The easing gallery, top row to bottom row. Each racing dot's `index` (set in
+// the scene) selects its curve here, so this order must match the scene's rows.
+// A broad sample of the 16 built-in curves — polynomial, back (overshoot),
+// elastic, bounce, and one custom cubic-bezier (see BEZIER below).
+export const EASINGS: EasingType[] = [
+ EasingType.Linear,
+ EasingType.EaseInQuad,
+ EasingType.EaseOutQuad,
+ EasingType.EaseInOutQuad,
+ EasingType.EaseInCubic,
+ EasingType.EaseOutCubic,
+ EasingType.EaseInOutCubic,
+ EasingType.EaseOutBack,
+ EasingType.EaseInOutBack,
+ EasingType.EaseOutElastic,
+ EasingType.EaseOutBounce,
+ EasingType.CubicBezier,
+];
+
+// Gallery: every dot races the same world-X track, so the different easings
+// visibly spread apart and regroup. Must match the rails authored in the scene.
+export const RACE_FROM = -620;
+export const RACE_TO = -120;
+export const RACE_DURATION = 2.4;
+
+// Control points for the one Cubic-Bezier row — an "anticipate then overshoot"
+// curve, applied with TweenHandle.bezier().
+export const BEZIER = { p1x: 0.6, p1y: -0.4, p2x: 0.4, p2y: 1.4 };
+
+// Hero: an endless choreography built from tween.sequence() with nested
+// tween.parallel() (move → spin+colour → move → spin+colour, forever).
+export const HERO_TRAVEL = 150;
+export const HERO_MOVE_DURATION = 0.7;
+export const HERO_SPIN_DURATION = 0.6;
+
+// Comet: click anywhere to fling it to the cursor with an overshooting ease
+// and an elastic size pop.
+export const COMET_DURATION = 0.8;
+export const COMET_SIZE = 30;
+export const COMET_POP = 48;
diff --git a/examples/tween-animation/src/main.ts b/examples/tween-animation/src/main.ts
index c3ba336ef..c9e5111d4 100644
--- a/examples/tween-animation/src/main.ts
+++ b/examples/tween-animation/src/main.ts
@@ -1,6 +1,21 @@
-import { addStartupSystem } from 'esengine';
+// Tween Animation — a tour of the engine's built-in tween system (the `Tween`
+// resource: `tween.to(...)`, `sequence()`, `parallel()`, `.bezier()`, easings).
+//
+// • Easing gallery — a column of dots races the same track, each with a
+// different easing curve, so they visibly spread apart and regroup.
+// • Hero — an endless sequence() of move → spin+colour steps, each
+// spin/colour pair run together with parallel().
+// • Comet — click anywhere and it tweens to the cursor with an
+// overshooting ease and an elastic size pop.
+//
+// Tweens are driven by the built-in TweenSystem (via the AnimationPlugin); a
+// system just starts them through the `Tween` resource. The C++ fast-path
+// writes Transform/Sprite directly each frame — no per-frame lerp code here.
+import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
import './components';
import { setupSystem } from './systems/setup';
+import { cometSystem } from './systems/comet';
addStartupSystem(setupSystem);
+addSystemToSchedule(Schedule.Update, cometSystem);
diff --git a/examples/tween-animation/src/systems/comet.ts b/examples/tween-animation/src/systems/comet.ts
new file mode 100644
index 000000000..9803a3e6f
--- /dev/null
+++ b/examples/tween-animation/src/systems/comet.ts
@@ -0,0 +1,33 @@
+import {
+ defineSystem, Query, Res, Transform, Input, UICameraInfo,
+ Tween, TweenAPI, TweenTarget, EasingType,
+} from 'esengine';
+import type { UICameraData } from 'esengine';
+import { Comet } from '../components';
+import { COMET_DURATION, COMET_SIZE, COMET_POP } from '../config';
+
+// Left-click flings the comet to the cursor: cancel whatever it was doing, then
+// start fresh position tweens (from its live position) with an overshooting ease,
+// plus a parallel elastic size pop for arrival juice. Clicking mid-flight simply
+// retargets — cancelAll clears the in-progress tweens first.
+export const cometSystem = defineSystem(
+ [Res(Tween), Res(Input), Res(UICameraInfo), Query(Transform, Comet)],
+ (tween: TweenAPI, input, camera: UICameraData, comets) => {
+ if (!camera.valid || !input.isMouseButtonPressed(0)) return;
+
+ const targetX = camera.worldMouseX;
+ const targetY = camera.worldMouseY;
+ for (const [entity, transform] of comets) {
+ const fromX = transform.position.x;
+ const fromY = transform.position.y;
+ tween.cancelAll(entity);
+ tween.to(entity, TweenTarget.PositionX, fromX, targetX, COMET_DURATION, { easing: EasingType.EaseOutBack });
+ tween.to(entity, TweenTarget.PositionY, fromY, targetY, COMET_DURATION, { easing: EasingType.EaseOutBack });
+ tween.parallel([
+ tween.to(entity, TweenTarget.SizeX, COMET_POP, COMET_SIZE, COMET_DURATION, { easing: EasingType.EaseOutElastic }),
+ tween.to(entity, TweenTarget.SizeY, COMET_POP, COMET_SIZE, COMET_DURATION, { easing: EasingType.EaseOutElastic }),
+ ]);
+ }
+ },
+ { name: 'CometSystem' },
+);
diff --git a/examples/tween-animation/src/systems/setup.ts b/examples/tween-animation/src/systems/setup.ts
index 1882f2fed..4aabda703 100644
--- a/examples/tween-animation/src/systems/setup.ts
+++ b/examples/tween-animation/src/systems/setup.ts
@@ -1,60 +1,51 @@
import {
- defineSystem, Query, Res,
- Transform, Sprite, Tween, TweenAPI, TweenTarget, EasingType, LoopMode,
+ defineSystem, Query, Res, Transform,
+ Tween, TweenAPI, TweenTarget, EasingType, LoopMode,
} from 'esengine';
-import { EasingDemo, ScaleDemo, RotationDemo, ColorDemo } from '../components';
-
-const EASING_TYPES = [
- EasingType.Linear,
- EasingType.EaseInQuad,
- EasingType.EaseOutQuad,
- EasingType.EaseInOutQuad,
- EasingType.EaseInCubic,
- EasingType.EaseOutBounce,
-];
+import { GalleryDot, Hero } from '../components';
+import {
+ EASINGS, RACE_FROM, RACE_TO, RACE_DURATION, BEZIER,
+ HERO_TRAVEL, HERO_MOVE_DURATION, HERO_SPIN_DURATION,
+} from '../config';
-const X_FROM = -250;
-const X_TO = 250;
-const DURATION = 2;
+// One lap of the hero choreography, re-armed on completion so it loops forever.
+// sequence() runs each factory in turn; the spin + colour steps are grouped with
+// parallel() so they play together. Rotating 0→360 leaves the same orientation,
+// and the colour returns to its start, so every lap begins cleanly.
+function loopHero(tween: TweenAPI, hero: number, centerX: number): void {
+ tween.sequence([
+ () => tween.to(hero, TweenTarget.PositionX, centerX - HERO_TRAVEL, centerX + HERO_TRAVEL, HERO_MOVE_DURATION, { easing: EasingType.EaseInOutCubic }),
+ () => tween.parallel([
+ tween.to(hero, TweenTarget.RotationZ, 0, 360, HERO_SPIN_DURATION, { easing: EasingType.EaseOutBack }),
+ tween.to(hero, TweenTarget.ColorR, 0.35, 1.0, HERO_SPIN_DURATION, { easing: EasingType.EaseInOutQuad }),
+ ]),
+ () => tween.to(hero, TweenTarget.PositionX, centerX + HERO_TRAVEL, centerX - HERO_TRAVEL, HERO_MOVE_DURATION, { easing: EasingType.EaseInOutCubic }),
+ () => tween.parallel([
+ tween.to(hero, TweenTarget.RotationZ, 0, 360, HERO_SPIN_DURATION, { easing: EasingType.EaseInOutBack }),
+ tween.to(hero, TweenTarget.ColorR, 1.0, 0.35, HERO_SPIN_DURATION, { easing: EasingType.EaseInOutQuad }),
+ ]),
+ ]).onComplete(() => loopHero(tween, hero, centerX));
+}
+// Starts every passive tween once at startup: the gallery race and the hero lap.
export const setupSystem = defineSystem(
- [Res(Tween), Query(Transform, EasingDemo), Query(Transform, ScaleDemo), Query(Transform, RotationDemo), Query(Transform, ColorDemo)],
- (tween: TweenAPI, easings, scales, rotations, colors) => {
- for (const [entity, _t, demo] of easings) {
- tween.to(entity, TweenTarget.PositionX, X_FROM, X_TO, DURATION, {
- easing: EASING_TYPES[demo.easingIndex] ?? EasingType.Linear,
- loop: LoopMode.PingPong,
- });
- }
-
- for (const [entity] of scales) {
- tween.to(entity, TweenTarget.ScaleX, 0.5, 2.0, 1.0, {
- easing: EasingType.EaseInOutQuad,
- loop: LoopMode.PingPong,
- });
- tween.to(entity, TweenTarget.ScaleY, 0.5, 2.0, 1.0, {
- easing: EasingType.EaseInOutQuad,
+ [Res(Tween), Query(GalleryDot), Query(Transform, Hero)],
+ (tween: TweenAPI, dots, heroes) => {
+ for (const [entity, dot] of dots) {
+ const easing = EASINGS[dot.index] ?? EasingType.Linear;
+ const handle = tween.to(entity, TweenTarget.PositionX, RACE_FROM, RACE_TO, RACE_DURATION, {
+ easing,
loop: LoopMode.PingPong,
});
+ // The one custom-curve row supplies its bezier control points.
+ if (easing === EasingType.CubicBezier) {
+ handle.bezier(BEZIER.p1x, BEZIER.p1y, BEZIER.p2x, BEZIER.p2y);
+ }
}
- for (const [entity] of rotations) {
- tween.to(entity, TweenTarget.RotationZ, 0, 360, 3.0, {
- easing: EasingType.Linear,
- loop: LoopMode.Restart,
- });
- }
-
- for (const [entity] of colors) {
- tween.to(entity, TweenTarget.ColorR, 1, 0, 2, {
- loop: LoopMode.PingPong,
- easing: EasingType.EaseInOutQuad,
- });
- tween.to(entity, TweenTarget.ColorG, 0, 1, 2, {
- loop: LoopMode.PingPong,
- easing: EasingType.EaseInOutQuad,
- });
+ for (const [entity, transform] of heroes) {
+ loopHero(tween, entity, transform.position.x);
}
},
- { name: 'SetupSystem' }
+ { name: 'SetupSystem' },
);
diff --git a/examples/tween-animation/thumbnail.png b/examples/tween-animation/thumbnail.png
index e31c950dc..3c7293ed4 100644
Binary files a/examples/tween-animation/thumbnail.png and b/examples/tween-animation/thumbnail.png differ