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(examples): cutscene — a code-free FSM-driven timeline

yhha256a118ff85
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index fb1558748..bb5838ce5 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -201,8 +201,9 @@ async function buildAppAndRun(msg: InitMessage): Promise<void> {
});
// Realm-local debug handle for automation/diagnostics (mirrors the headless
// host's __estellaHeadless): the editor can't reach into this OOPIF except by
- // main-process frame eval, and the eval needs SOMETHING to query.
- (window as unknown as { __estellaPlay?: unknown }).__estellaPlay = { app };
+ // main-process frame eval, and the eval needs SOMETHING to query. getComponent
+ // lets a probe read component data by name (world.get needs the def).
+ (window as unknown as { __estellaPlay?: unknown }).__estellaPlay = { app, getComponent };
// Surface a failed handshake as a boot error rather than a silent
// half-session (the app keeps running; the role reverted to offline).
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdx
index 73c1a94eb..649d2f6c5 100644
--- a/docs/astro/src/content/docs/guides/ai.mdx
+++ b/docs/astro/src/content/docs/guides/ai.mdx
@@ -130,6 +130,10 @@ FSM only flips its flags. Built-in names never shadow yours: if you register an
action or condition under the same name, your registration wins. Avoid the
`timeline.` prefix for game names to keep the namespaces apart.
+The [`cutscene` example](https://github.com/esengine/estella/tree/master/examples/cutscene)
+is this pattern end-to-end: an intro timeline plays on scene start, gameplay
+unlocks when it completes, and R replays it — with zero registered actions.
+
## Perception
A `Perceiver` scans for the nearest visible `PerceptionTarget` each frame and writes
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
index 06b181e92..e2d1c5f0f 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
@@ -116,6 +116,10 @@ registerFsm('intro', {
旗标。内建名字永远不会遮蔽你的注册:同名时你的注册获胜。游戏侧的名字请避开
`timeline.` 前缀,保持命名空间分离。
+[`cutscene` 示例](https://github.com/esengine/estella/tree/master/examples/cutscene)
+就是这个模式的完整落地:场景开始即播开场时间轴,播完解锁操作,按 R 重播——
+全程零注册动作。
+
## 感知
`Perceiver` 每帧扫描最近的、可见的 `PerceptionTarget`,把结果写进同一实体上的 `Perception`
diff --git a/examples/README.md b/examples/README.md
index fda4fb8e3..c340b59e4 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -19,6 +19,7 @@ for your own game.
| **sprite-animation** | Animation | Frame animation via `.esanim` clips with an idle/walk switcher. |
| **spine-demo** | Animation | A Spine skeleton cycling idle/walk/run/jump/shoot (1-5 to switch). |
| **tween-animation** | Animation | Ease positions, scales and colors over time. |
+| **cutscene** | Animation | A code-free cutscene: an FSM state plays a timeline via the built-in `timeline.play` / `timeline.finished` names, then hands over to gameplay (R to replay). |
| **input-demo** | Input | Keyboard, mouse and pointer input with a motion trail. |
| **audio-demo** | Audio | One-shot SFX and a beat visualizer driven by playback. |
| **collision-layers** | Physics | Layer-based collision filtering between groups of bodies. |
@@ -33,6 +34,8 @@ for your own game.
| **ui-interaction** | UI | Dragging, focus and pointer interaction. |
| **ui-layout** | UI | Flexbox-style responsive UI layout. |
| **ui-list** | UI | A virtualized list and grid — `createListView`, live data, `scrollToIndex`. |
+| **enemy-ai** | AI | A state machine drives enemies to patrol, sense the player, and chase via A* navigation. |
+| **multiplayer-arena** | Networking | Server-authoritative multiplayer: each player steers a replicated pawn ('2 Players' in the Play dropdown runs listen server + client). |
| **platformer** | Game | A tiny platformer — run, jump and collect coins. |
| **space-shooter** | Game | A vertical shmup with prefabs, a HUD and a difficulty ramp. |
diff --git a/examples/cutscene/.gitignore b/examples/cutscene/.gitignore
new file mode 100644
index 000000000..359472ac2
--- /dev/null
+++ b/examples/cutscene/.gitignore
@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+.esengine/cache/
diff --git a/examples/cutscene/README.md b/examples/cutscene/README.md
new file mode 100644
index 000000000..4d4d91d97
--- /dev/null
+++ b/examples/cutscene/README.md
@@ -0,0 +1,31 @@
+# Cutscene
+
+A **code-free cutscene** driven by a state machine. The director entity carries a
+`StateMachineAgent` and a `TimelinePlayer`; its FSM (`assets/ai/director.esfsm`)
+uses only the engine's **built-in AI names**:
+
+- entering the `Cutscene` state runs `timeline.play` → the intro timeline starts;
+- the `timeline.finished` condition fires when the clip completes → transition to
+ `Gameplay`.
+
+The timeline (`assets/timelines/intro.estimeline`) hops the hero onto the stage
+(property track on the `Hero` child) and holds the letterbox bars visible for the
+shot (activation tracks on `BarTop`/`BarBottom`).
+
+Game code (`src/systems/gameplay.ts`) never touches the timeline — it reads the
+FSM's observable `current` state to enable hero movement, and fires the `replay`
+trigger.
+
+## Controls
+
+| Input | Action |
+|---|---|
+| Arrow keys / WASD | Move the hero (only once the cutscene has finished). |
+| R | Replay the cutscene — the finished clip restarts from the top. |
+
+## What to look at
+
+- `assets/ai/director.esfsm` — the whole cutscene flow, no registered actions.
+- `assets/timelines/intro.estimeline` — property + activation tracks by child path.
+- `src/systems/gameplay.ts` — gating gameplay on `StateMachineAgent.current` and
+ firing a trigger through the `AiFsm` resource.
diff --git a/examples/cutscene/assets/ai/director.esfsm b/examples/cutscene/assets/ai/director.esfsm
new file mode 100644
index 000000000..e0f1fdcc1
--- /dev/null
+++ b/examples/cutscene/assets/ai/director.esfsm
@@ -0,0 +1,22 @@
+{
+ "initial": "Cutscene",
+ "states": [
+ {
+ "name": "Cutscene",
+ "x": 80,
+ "y": 110,
+ "onEnter": "timeline.play",
+ "transitions": [
+ { "to": "Gameplay", "condition": "timeline.finished" }
+ ]
+ },
+ {
+ "name": "Gameplay",
+ "x": 380,
+ "y": 110,
+ "transitions": [
+ { "to": "Cutscene", "trigger": "replay" }
+ ]
+ }
+ ]
+}
diff --git a/examples/cutscene/assets/ai/director.esfsm.meta b/examples/cutscene/assets/ai/director.esfsm.meta
new file mode 100644
index 000000000..5ab9dd2ec
--- /dev/null
+++ b/examples/cutscene/assets/ai/director.esfsm.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "7f41b8c2-95d3-4a06-8e17-c3a2d90f651b",
+ "version": "1.0",
+ "type": "statemachine",
+ "importer": { "autoMigrate": true }
+}
diff --git a/examples/cutscene/assets/scenes/main.esscene b/examples/cutscene/assets/scenes/main.esscene
new file mode 100644
index 000000000..79e0cd697
--- /dev/null
+++ b/examples/cutscene/assets/scenes/main.esscene
@@ -0,0 +1,85 @@
+{
+ "version": "1.0",
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 340, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Director",
+ "parent": null,
+ "children": [2, 3, 4],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "StateMachineAgent", "data": { "fsm": "assets/ai/director.esfsm" } },
+ { "type": "TimelinePlayer", "data": { "timeline": "assets/timelines/intro.estimeline", "wrapMode": "once" } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Hero",
+ "parent": 1,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -380, "y": -108, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 48, "y": 48 }, "color": { "r": 0.35, "g": 0.85, "b": 1, "a": 1 }, "layer": 2 } },
+ { "type": "HeroControl", "data": { "speed": 260 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "BarTop",
+ "parent": 1,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 270, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 1100, "y": 140 }, "color": { "r": 0.05, "g": 0.05, "b": 0.07, "a": 1 }, "layer": 10 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 4,
+ "name": "BarBottom",
+ "parent": 1,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": -270, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 1100, "y": 140 }, "color": { "r": 0.05, "g": 0.05, "b": 0.07, "a": 1 }, "layer": 10 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 5,
+ "name": "Spot",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": -108, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 64, "y": 64 }, "color": { "r": 0.2, "g": 0.5, "b": 0.45, "a": 0.5 }, "layer": 1 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 6,
+ "name": "Stage",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": -140, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 1100, "y": 16 }, "color": { "r": 0.25, "g": 0.27, "b": 0.3, "a": 1 }, "layer": 1 } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/examples/cutscene/assets/scenes/main.esscene.meta b/examples/cutscene/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..bbabfad20
--- /dev/null
+++ b/examples/cutscene/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "3c9d51e7-6a2b-48f0-b4d8-92e15c7a03f4",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/cutscene/assets/timelines/intro.estimeline b/examples/cutscene/assets/timelines/intro.estimeline
new file mode 100644
index 000000000..1077bfce6
--- /dev/null
+++ b/examples/cutscene/assets/timelines/intro.estimeline
@@ -0,0 +1,47 @@
+{
+ "version": "1.1",
+ "type": "timeline",
+ "duration": 3,
+ "wrapMode": "once",
+ "tracks": [
+ {
+ "type": "property",
+ "name": "Hero enters",
+ "childPath": "Hero",
+ "component": "Transform",
+ "channels": [
+ {
+ "property": "position.x",
+ "keyframes": [
+ { "time": 0, "value": -380, "inTangent": 0, "outTangent": 0, "interpolation": "easeInOut" },
+ { "time": 2.4, "value": 0, "inTangent": 0, "outTangent": 0, "interpolation": "linear" }
+ ]
+ },
+ {
+ "property": "position.y",
+ "keyframes": [
+ { "time": 0, "value": -108, "inTangent": 0, "outTangent": 0, "interpolation": "linear" },
+ { "time": 0.6, "value": -108, "inTangent": 0, "outTangent": 0, "interpolation": "easeOut" },
+ { "time": 0.9, "value": -40, "inTangent": 0, "outTangent": 0, "interpolation": "easeIn" },
+ { "time": 1.2, "value": -108, "inTangent": 0, "outTangent": 0, "interpolation": "linear" },
+ { "time": 1.7, "value": -108, "inTangent": 0, "outTangent": 0, "interpolation": "easeOut" },
+ { "time": 2.0, "value": -40, "inTangent": 0, "outTangent": 0, "interpolation": "easeIn" },
+ { "time": 2.3, "value": -108, "inTangent": 0, "outTangent": 0, "interpolation": "linear" }
+ ]
+ }
+ ]
+ },
+ {
+ "type": "activation",
+ "name": "Letterbox top",
+ "childPath": "BarTop",
+ "ranges": [{ "start": 0, "end": 3 }]
+ },
+ {
+ "type": "activation",
+ "name": "Letterbox bottom",
+ "childPath": "BarBottom",
+ "ranges": [{ "start": 0, "end": 3 }]
+ }
+ ]
+}
diff --git a/examples/cutscene/assets/timelines/intro.estimeline.meta b/examples/cutscene/assets/timelines/intro.estimeline.meta
new file mode 100644
index 000000000..9d609e48d
--- /dev/null
+++ b/examples/cutscene/assets/timelines/intro.estimeline.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "e58a204d-1c7f-4b93-a6e0-48d5f217c9ab",
+ "version": "1.0",
+ "type": "animation",
+ "importer": { "autoMigrate": true }
+}
diff --git a/examples/cutscene/project.esproject b/examples/cutscene/project.esproject
new file mode 100644
index 000000000..40716b4d9
--- /dev/null
+++ b/examples/cutscene/project.esproject
@@ -0,0 +1,13 @@
+{
+ "formatVersion": "1",
+ "name": "Cutscene",
+ "description": "A code-free cutscene: an FSM state plays a timeline through the built-in timeline.play action and hands over to gameplay when timeline.finished fires.",
+ "tag": "Animation",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 960,
+ "height": 640
+ },
+ "spineVersion": "none"
+}
diff --git a/examples/cutscene/src/components.ts b/examples/cutscene/src/components.ts
new file mode 100644
index 000000000..e79bea377
--- /dev/null
+++ b/examples/cutscene/src/components.ts
@@ -0,0 +1,12 @@
+import { defineComponent } from 'esengine';
+
+// The project's declaration entry (src/components.ts): user component/tag
+// definitions only — no systems, no createWebApp. The editor extracts schemas
+// from here so the inspector knows their fields without running project code.
+// (StateMachineAgent / TimelinePlayer are engine built-ins, so they aren't
+// declared.)
+
+/** Marks the arrow/WASD-controlled hero and carries its move speed. */
+export const HeroControl = defineComponent('HeroControl', {
+ speed: 260,
+});
diff --git a/examples/cutscene/src/main.ts b/examples/cutscene/src/main.ts
new file mode 100644
index 000000000..93e4ca770
--- /dev/null
+++ b/examples/cutscene/src/main.ts
@@ -0,0 +1,10 @@
+import { addSystemToSchedule, Schedule } from 'esengine';
+
+import './components';
+import { heroMoveSystem, replaySystem } from './systems/gameplay';
+
+// Only project-specific systems are registered here. The FSM tick
+// (StateMachineAgent) and timeline playback (TimelinePlayer) are the engine's
+// built-in plugins — the cutscene itself needs no wiring at all.
+addSystemToSchedule(Schedule.Update, heroMoveSystem);
+addSystemToSchedule(Schedule.Update, replaySystem);
diff --git a/examples/cutscene/src/systems/gameplay.ts b/examples/cutscene/src/systems/gameplay.ts
new file mode 100644
index 000000000..d788dabce
--- /dev/null
+++ b/examples/cutscene/src/systems/gameplay.ts
@@ -0,0 +1,51 @@
+import {
+ defineSystem, Query, Mut, Res, Time, Input, Transform,
+ StateMachineAgent, AiFsm,
+} from 'esengine';
+import { HeroControl } from '../components';
+
+// The whole cutscene runs in DATA: the director's FSM (assets/ai/director.esfsm)
+// uses only the engine's built-in names — `timeline.play` on entering the
+// Cutscene state, `timeline.finished` to leave it. Game code never touches the
+// timeline; it just reads the FSM's observable state and moves the hero while
+// the director is in Gameplay.
+
+export const heroMoveSystem = defineSystem(
+ [Query(Mut(Transform), HeroControl), Query(StateMachineAgent), Res(Input), Res(Time)],
+ (heroes, directors, input, time) => {
+ let inGameplay = false;
+ for (const [, agent] of directors) {
+ if (agent.current === 'Gameplay') { inGameplay = true; break; }
+ }
+ if (!inGameplay) return;
+
+ for (const [, transform, hero] of heroes) {
+ let dx = 0;
+ let dy = 0;
+ if (input.isKeyDown('KeyW') || input.isKeyDown('ArrowUp')) dy += 1;
+ if (input.isKeyDown('KeyS') || input.isKeyDown('ArrowDown')) dy -= 1;
+ if (input.isKeyDown('KeyA') || input.isKeyDown('ArrowLeft')) dx -= 1;
+ if (input.isKeyDown('KeyD') || input.isKeyDown('ArrowRight')) dx += 1;
+ if (dx === 0 && dy === 0) continue;
+ const len = Math.sqrt(dx * dx + dy * dy);
+ transform.position.x += (dx / len) * hero.speed * time.delta;
+ transform.position.y += (dy / len) * hero.speed * time.delta;
+ }
+ },
+ { name: 'HeroMoveSystem' },
+);
+
+// R fires the `replay` trigger; the Gameplay → Cutscene transition consumes it
+// and the Cutscene state's onEnter replays the finished clip from the top (the
+// TimelinePlayer replay contract). Gated on Gameplay so a press during the
+// cutscene can't queue a stale replay.
+export const replaySystem = defineSystem(
+ [Query(StateMachineAgent), Res(Input), Res(AiFsm)],
+ (directors, input, fsm) => {
+ if (!input.isKeyPressed('KeyR')) return;
+ for (const [entity, agent] of directors) {
+ if (agent.current === 'Gameplay') fsm.fire(entity, 'replay');
+ }
+ },
+ { name: 'CutsceneReplaySystem' },
+);
diff --git a/examples/cutscene/tsconfig.json b/examples/cutscene/tsconfig.json
new file mode 100644
index 000000000..0a8528b29
--- /dev/null
+++ b/examples/cutscene/tsconfig.json
@@ -0,0 +1,22 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "baseUrl": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"],
+ "@esengine/editor": ["./.esengine/editor/index.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}