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
examples(enemy-ai): flagship navigation + state-machine demo
esengine632e6c623b48
diff --git a/examples/enemy-ai/README.md b/examples/enemy-ai/README.mdnew file mode 100644index 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.esscenenew file mode 100644index 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.esprojectnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"]+}