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(examples): cutscene — a code-free FSM-driven timeline
yhha256a118ff85
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.tsindex 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.mdxindex 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 anaction 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.+## PerceptionA `Perceiver` scans for the nearest visible `PerceptionTarget` each frame and writesdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdxindex 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.mdindex 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/.gitignorenew file mode 100644index 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.mdnew file mode 100644index 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.esfsmnew file mode 100644index 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.metanew file mode 100644index 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.esscenenew file mode 100644index 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.metanew file mode 100644index 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.estimelinenew file mode 100644index 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.metanew file mode 100644index 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.esprojectnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"]+}