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(enemy-ai): flagship navigation + state-machine demo

esengine632e6c623b48
diff --git a/examples/enemy-ai/README.md b/examples/enemy-ai/README.md
new file mode 100644
index 000000000..856b0b2fc
--- /dev/null
+++ b/examples/enemy-ai/README.md
@@ -0,0 +1,29 @@
+# Enemy AI
+
+Two enemies **patrol** until they **sense** the player, then **chase** via A\*
+navigation — a state machine and the nav agent working together. Move the player
+with **WASD** / arrow keys; walk within range and the red enemies path toward you,
+break off and idle when you slip away.
+
+## What it shows
+
+- **State machine** (`registerFsm`) as pure data: `Patrol ⇄ Chase`, switched by a
+ `seesPlayer` blackboard guard. Authorable in the editor's State Machine editor
+ (a `.esfsm` asset) or in code as here.
+- **Named actions** (`registerAction`): the `chase` leaf steers the agent's
+ NavAgent at the player — decision (FSM) and locomotion (nav) stay decoupled.
+- **Navigation** (`NavGrid` + `NavAgent` + `setNavDestination`): grid A\* plans the
+ path; the built-in nav plugin follows it. No per-frame movement code.
+- **Perception** feeding the blackboard: a small system writes `seesPlayer` from
+ enemy↔player distance, which the FSM guard reads.
+
+## Files
+
+- `src/enemy.ts` — the FSM definition, the `chase` action, the perception system,
+ and the startup grid.
+- `src/player.ts` — the WASD-controlled player.
+- `src/main.ts` — registers the systems (the fsm/nav plugins are built in).
+
+The `StateMachineAgent` and `NavAgent` components are attached to the enemies in
+`assets/scenes/main.esscene`; the FSM they reference (`"enemy"`) is registered in
+code. Both are engine built-ins — no plugin wiring needed.
diff --git a/examples/enemy-ai/assets/scenes/main.esscene b/examples/enemy-ai/assets/scenes/main.esscene
new file mode 100644
index 000000000..844b06707
--- /dev/null
+++ b/examples/enemy-ai/assets/scenes/main.esscene
@@ -0,0 +1,55 @@
+{
+ "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": "Player",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -200, "y": -120, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 40, "y": 40 }, "color": { "r": 0.3, "g": 0.8, "b": 1, "a": 1 }, "layer": 2 } },
+ { "type": "PlayerControl", "data": { "speed": 240 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Enemy A",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 200, "y": 150, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 36, "y": 36 }, "color": { "r": 0.9, "g": 0.35, "b": 0.3, "a": 1 }, "layer": 2 } },
+ { "type": "StateMachineAgent", "data": { "fsm": "enemy" } },
+ { "type": "NavAgent", "data": { "speed": 120, "repathInterval": 0.35 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "Enemy B",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 260, "y": -160, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 36, "y": 36 }, "color": { "r": 0.95, "g": 0.55, "b": 0.25, "a": 1 }, "layer": 2 } },
+ { "type": "StateMachineAgent", "data": { "fsm": "enemy" } },
+ { "type": "NavAgent", "data": { "speed": 95, "repathInterval": 0.5 } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/examples/enemy-ai/project.esproject b/examples/enemy-ai/project.esproject
new file mode 100644
index 000000000..3ed5f0934
--- /dev/null
+++ b/examples/enemy-ai/project.esproject
@@ -0,0 +1,13 @@
+{
+ "formatVersion": "1",
+ "name": "Enemy AI",
+ "description": "A state machine drives enemies to patrol, sense the player, and chase via A* navigation.",
+ "tag": "AI",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 960,
+ "height": 640
+ },
+ "spineVersion": "none"
+}
diff --git a/examples/enemy-ai/src/components.ts b/examples/enemy-ai/src/components.ts
new file mode 100644
index 000000000..452b109bf
--- /dev/null
+++ b/examples/enemy-ai/src/components.ts
@@ -0,0 +1,11 @@
+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 / NavAgent are engine built-ins, so they aren't declared.)
+
+/** Marks the WASD-controlled player and carries its move speed. */
+export const PlayerControl = defineComponent('PlayerControl', {
+ speed: 240,
+});
diff --git a/examples/enemy-ai/src/enemy.ts b/examples/enemy-ai/src/enemy.ts
new file mode 100644
index 000000000..defcd5fa5
--- /dev/null
+++ b/examples/enemy-ai/src/enemy.ts
@@ -0,0 +1,52 @@
+import {
+ defineSystem, Query, Res, Transform, GetWorld,
+ registerFsm, registerAction, setNavDestination, Nav, NavGrid, AiFsm, StateMachineAgent,
+} from 'esengine';
+import { PlayerControl } from './components';
+
+// The enemy brain, as data: patrol until the player is sensed, chase while seen,
+// break off when lost. `seesPlayer` is a blackboard flag the perception system
+// writes; `chase` is a named action resolved from the registry below.
+registerFsm('enemy', {
+ initial: 'Patrol',
+ states: [
+ { name: 'Patrol', transitions: [{ to: 'Chase', guard: { key: 'seesPlayer', op: 'truthy' } }] },
+ { name: 'Chase', onUpdate: 'chase', transitions: [{ to: 'Patrol', guard: { key: 'seesPlayer', op: 'falsy' } }] },
+ ],
+});
+
+// Chase leaf: steer this agent's NavAgent at the player's live position. The
+// nav layer plans the A* path and moves the body — the action only sets intent.
+registerAction('chase', (ctx) => {
+ const players = ctx.world.getEntitiesWithComponents([PlayerControl, Transform]);
+ const player = players[0];
+ if (player === undefined) return;
+ const p = ctx.world.get(player, Transform);
+ setNavDestination(ctx.world, ctx.entity, { x: p.position.x, y: p.position.y });
+});
+
+/** Install an open navigation grid over the arena on startup. */
+export const setupNavGridSystem = defineSystem(
+ [Res(Nav)],
+ (nav) => {
+ nav.setGrid(new NavGrid({ width: 60, height: 44, cellSize: 20, origin: { x: -600, y: -440 } }));
+ },
+ { name: 'SetupNavGridSystem' },
+);
+
+const SENSE_RANGE = 180;
+
+/** Perception: set each enemy's `seesPlayer` blackboard flag that the FSM guard reads. */
+export const enemySenseSystem = defineSystem(
+ [Query(Transform, StateMachineAgent), Res(AiFsm), GetWorld()],
+ (enemies, aifsm, world) => {
+ const players = world.getEntitiesWithComponents([PlayerControl, Transform]);
+ if (players.length === 0) return;
+ const pp = world.get(players[0], Transform).position;
+ for (const [entity, tf] of enemies) {
+ const d = Math.hypot(pp.x - tf.position.x, pp.y - tf.position.y);
+ aifsm.blackboard(entity).set('seesPlayer', d < SENSE_RANGE);
+ }
+ },
+ { name: 'EnemySenseSystem' },
+);
diff --git a/examples/enemy-ai/src/main.ts b/examples/enemy-ai/src/main.ts
new file mode 100644
index 000000000..6bd2037a9
--- /dev/null
+++ b/examples/enemy-ai/src/main.ts
@@ -0,0 +1,10 @@
+import { addSystemToSchedule, Schedule } from 'esengine';
+import { keyboardMoveSystem } from './player';
+import { setupNavGridSystem, enemySenseSystem } from './enemy';
+
+// The nav grid is built once; perception + player movement run every frame. The
+// FSM tick (StateMachineAgent) and nav follow (NavAgent) are driven by the
+// engine's built-in fsm/nav plugins — no per-project wiring needed.
+addSystemToSchedule(Schedule.Startup, setupNavGridSystem);
+addSystemToSchedule(Schedule.Update, keyboardMoveSystem);
+addSystemToSchedule(Schedule.Update, enemySenseSystem);
diff --git a/examples/enemy-ai/src/player.ts b/examples/enemy-ai/src/player.ts
new file mode 100644
index 000000000..9789dbe80
--- /dev/null
+++ b/examples/enemy-ai/src/player.ts
@@ -0,0 +1,23 @@
+import {
+ defineSystem, Query, Mut, Res, Time, Input, Transform,
+} from 'esengine';
+import { PlayerControl } from './components';
+
+export const keyboardMoveSystem = defineSystem(
+ [Query(Mut(Transform), PlayerControl), Res(Input), Res(Time)],
+ (query, input, time) => {
+ for (const [, transform, player] of query) {
+ 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) * player.speed * time.delta;
+ transform.position.y += (dy / len) * player.speed * time.delta;
+ }
+ },
+ { name: 'PlayerMoveSystem' },
+);
diff --git a/examples/enemy-ai/tsconfig.json b/examples/enemy-ai/tsconfig.json
new file mode 100644
index 000000000..0a8528b29
--- /dev/null
+++ b/examples/enemy-ai/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"]
+}