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.

release: v0.15.0 — gameplay AI docs + changelog

esengine28c69ca4b965
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 70c743172..b7ca794c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,70 @@ each entry.
## [Unreleased]
+## [0.15.0] - 2026-07-05
+
+The first feature release since the 0.14.0 licensing change — a large one. It adds a
+full gameplay AI layer, a rebuilt World Outliner, a complete tilemap painter, a
+first-class material system, a Sequencer, and much more, alongside deep internal
+re-architecture of the editor, renderer, and asset pipelines.
+
+### Added
+
+- **Gameplay AI layer.** Grid navigation with A\* pathfinding (`NavGrid`, `NavAgent`,
+ the `Nav` resource), a perception system (`Perceiver` / `PerceptionTarget` /
+ `Perception`), and two decision paradigms over one shared action/condition
+ registry — **state machines** (`.esfsm`) and **behavior trees** (`.esbt`) — each
+ with a visual node-graph editor. New guide: **Gameplay AI**.
+- **World Outliner** rebuilt to a UE-style `SSceneOutliner`: virtualized tree,
+ path-based first-class folders, real hidden/locked state (decoupled from component
+ enabled), reveal-on-select, keyboard navigation, token search, drag-to-reorder,
+ and a pluggable column registry.
+- **Tilemap painter** — stamp brush with flip/rotate and footprint preview, bucket &
+ line tools on a unified stroke driver, terrain/autotile, per-tile polygon collision
+ end-to-end, and a marquee select with copy / cut / paste / delete.
+- **Material system** — reflection-driven std140 UBO materials, Material Instances, a
+ Material Editor, static shader switches compiled to variants, 2D lighting (`Light2D`
+ directional/point/spot with normal maps), and a visual **Material Graph**.
+- **2D lighting & shadows** — `Light2D` on a dedicated Lit-2D channel plus
+ `ShadowCaster2D` for soft, directional 2D shadows; per-sprite parallax scrolling.
+- **Sequencer** — a UE-style timeline panel with a curve editor and auto-key
+ recording, backed by a pure-TypeScript timeline runtime.
+- **Animator** upgrades — nested (sub-)state machines, 1D blend states, exit-time
+ transitions, and Spine-driven animation (not just sprites).
+- **Input** — `defineInputMap` with named actions, gamepad support, data-driven
+ `.inputmap` assets, a visual input-map editor, and interactive rebinding.
+- **Physics** — a kinematic move-and-slide `CharacterController`, a Unity/UE-style
+ collision-layer matrix in Project Settings, full world/solver config threaded from
+ Project Settings, and contact/hit events.
+- **Editor viewport** — UE-style gizmo handles, any-entity picking, multi-select,
+ marquee, group transforms, nudge/snap, collider-shape overlays, and click-to-select
+ UI elements via the engine hit-test.
+- **Export targets** — playable-ad (single-file HTML), WeChat MiniGame
+ (`exportWeChat`), and a desktop (Electron) target.
+- **Subsystem observability** — a live **Engine Modules** panel reporting which
+ subsystems are loaded and stepping across both the edit and play realms.
+
+### Changed
+
+- Large internal re-architecture across the **editor** (model-as-truth state, a
+ versioned editor↔runtime protocol), the **renderer** (unified submission path,
+ device-owned pipeline state, single-source `.esshader` shaders), **serialization**,
+ and the **asset pipeline**. These touch engine internals, not the documented SDK
+ surface.
+- **UI runtime** modernized to fully SDF text (fill / outline / shadow), flex layout,
+ and theme tokens; the legacy Canvas2D text renderer was removed.
+- The **Apache-2.0 relicense** from 0.14.0 is carried into this release.
+
+### Fixed
+
+- Editor stability: a per-panel render error boundary, state-preserving hot reload,
+ and more robust asset-reference resolution — plus numerous tilemap, outliner,
+ physics, and export fixes.
+
+### SDK
+
+- `esengine` SDK **0.4.0** on npm.
+
## [0.14.0] - 2026-06-26
### Changed
@@ -53,6 +117,7 @@ not kept before this file was introduced — see the Git history at
`github.com/esengine/estella` for the full commit-level record since the first
commit on 2026-01-25.
-[Unreleased]: https://github.com/esengine/estella/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/esengine/estella/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/esengine/estella/compare/v0.14.0...v0.15.0
[0.14.0]: https://github.com/esengine/estella/compare/v0.13.0...v0.14.0
[0.13.0]: https://github.com/esengine/estella/compare/v0.12.3...v0.13.0
diff --git a/desktop/package.json b/desktop/package.json
index 4f2a08d4a..00c232497 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,6 +1,6 @@
{
"name": "@estella/editor",
- "version": "0.14.0",
+ "version": "0.15.0",
"private": true,
"license": "Apache-2.0",
"description": "Estella Editor — visual scene editor for the Estella 2D WASM engine",
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 93257684e..238dfb9af 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -52,6 +52,7 @@ export default defineConfig({
{ label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'guides/camera' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
+ { label: 'Gameplay AI', translations: { 'zh-CN': '游戏 AI' }, slug: 'guides/ai' },
{ label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },
{ label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'guides/timeline' },
{ label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdx
new file mode 100644
index 000000000..d81293b77
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/ai.mdx
@@ -0,0 +1,417 @@
+---
+title: Gameplay AI
+description: The gameplay AI layer — perception, grid navigation with A* pathfinding, state machines, and behavior trees, all driven by one shared registry of named actions and conditions and authored visually in the editor.
+---
+
+import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
+
+Estella's AI layer turns an entity into an actor that **senses**, **decides**, and
+**moves**. It is built from four cooperating pieces that share one design:
+
+<CardGrid>
+ <Card title="Perception" icon="magnifier">
+ A `Perceiver` senses nearby `PerceptionTarget`s within a sight cone and writes
+ what it sees into a `Perception` component.
+ </Card>
+ <Card title="Navigation" icon="rocket">
+ A `NavGrid` + A\* pathfinding moves a `NavAgent` to any world point, replanning
+ as the target moves.
+ </Card>
+ <Card title="State machines" icon="list-format">
+ A `StateMachineAgent` runs an `.esfsm` graph — states with enter/update/exit
+ hooks and guarded transitions.
+ </Card>
+ <Card title="Behavior trees" icon="puzzle">
+ A `BehaviorTreeAgent` runs an `.esbt` graph — selectors, sequences, decorators,
+ and leaves.
+ </Card>
+</CardGrid>
+
+The unifying idea: **state machines and behavior trees are two authoring paradigms
+over the same building blocks.** You register named *actions* and *conditions* once,
+in code, then wire them into either an FSM or a BT — graphs authored visually in the
+editor, not hardcoded. Perception feeds the decision; the decision drives navigation.
+
+<Aside type="note">
+ Everything here is pure TypeScript in the `esengine` core (no WebAssembly
+ side-module). All four plugins — perception, FSM, BT, and navigation — are added
+ automatically by the editor and the web runtime. You only wire plugins yourself in
+ a bare `new App()` (see [Custom app setup](#custom-app-setup)).
+</Aside>
+
+## The shared registry
+
+An **action** does something (chase, attack, play a sound); a **condition** answers
+a yes/no question (do I see the player?). You register each under a name, once, and
+both the FSM and the BT resolve those names against the same registry — so one set
+of leaves serves both paradigms.
+
+```typescript
+import { registerAction, registerCondition, Status, Perception, setNavDestination } from 'esengine';
+
+registerCondition('seesPlayer', (ctx) =>
+ ctx.has(Perception) && ctx.get(Perception).visible);
+
+registerAction('chase', (ctx) => {
+ const per = ctx.get(Perception);
+ setNavDestination(ctx.world, ctx.entity, { x: per.targetX, y: per.targetY });
+});
+```
+
+Every action and condition receives an **`AiContext`** for the agent it runs on. It
+is the same programming model as a `defineBehavior` update — entity, world, and
+commands access — plus a per-agent `blackboard`:
+
+| Member | Type | Description |
+|---|---|---|
+| `ctx.entity` | `Entity` | The agent this action/condition runs for. |
+| `ctx.dt` | `number` | Frame delta in seconds. |
+| `ctx.world` | `World` | Full world access for cross-entity reads. |
+| `ctx.commands` | `Commands` | Deferred spawn/despawn, safe mid-tick. |
+| `ctx.blackboard` | `Blackboard` | This agent's AI data plane (see [Blackboard](#the-blackboard)). |
+| `ctx.get(Comp)` | `ComponentData` | Read another component on **this** entity. |
+| `ctx.set(Comp, data)` | `void` | Write a component on **this** entity. |
+| `ctx.has(Comp)` | `boolean` | Whether this entity has `Comp`. |
+
+<Aside type="tip">
+ Register your actions and conditions at module load (top-level, or in a
+ `Schedule.Startup` system) so they exist before any agent ticks. The
+ registry is process-wide and shared across `App` instances.
+</Aside>
+
+### Action return values
+
+A **condition** always returns a `boolean`. An **action** may return a `Status`
+or nothing:
+
+```typescript
+export enum Status { Success = 'success', Failure = 'failure', Running = 'running' }
+```
+
+- In a **behavior tree**, a leaf returns `Status` to run across frames (`Running`),
+ succeed, or fail. Returning nothing counts as `Success`.
+- In a **state machine**, the return value is ignored — FSM actions are one-shot
+ side effects.
+
+Writing an action that returns `Status` lets the *same* action serve as a BT leaf and
+an FSM hook.
+
+## Perception
+
+A `Perceiver` scans for the nearest visible `PerceptionTarget` each frame and writes
+the result into a `Perception` component on the same entity. Decisions read
+`Perception`; sensing is just ECS data, not a side channel.
+
+```typescript
+import { Perceiver, PerceptionTarget, Perception } from 'esengine';
+
+// The hunter senses…
+cmds.spawn()
+ .insert(Transform, { position: { x: -200, y: 0, z: 0 } })
+ .insert(Perceiver, { range: 260, fovDegrees: 120 })
+ .insert(Perception, {}); // written every frame by the perception plugin
+
+// …anything tagged as a target.
+cmds.spawn()
+ .insert(Transform, { position: { x: 100, y: 0, z: 0 } })
+ .insert(PerceptionTarget, {});
+```
+
+| Component | Field | Default | Description |
+|---|---|---|---|
+| **`Perceiver`** | `range` | `220` | Sight range in world pixels. |
+| | `fovDegrees` | `360` | Field-of-view cone in degrees (`360` = omnidirectional). |
+| **`Perception`** | `visible` | `false` | A target is currently seen. |
+| | `distance` | `0` | Distance to the seen target. |
+| | `targetX`, `targetY` | `0` | Seen target position, world pixels. |
+| | `dirX`, `dirY` | `0` | Unit direction from observer to target. |
+| **`PerceptionTarget`** | *(tag)* | — | Marks an entity as sensable by `Perceiver`s. |
+
+The FOV cone is oriented by the perceiver's `Transform` rotation. `Perception` is a
+transient, runtime-only component — the plugin rewrites it every frame, so you never
+author its values.
+
+## Navigation
+
+Navigation moves an agent to a world point along a route that avoids blocked cells,
+using A\* over a **`NavGrid`**.
+
+### Building a grid
+
+A `NavGrid` is a rectangular grid of walkable/blocked cells. Install it on the `Nav`
+resource so agents can path against it:
+
+```typescript
+import { defineSystem, Res, Nav, NavGrid } from 'esengine';
+
+export const setupNav = defineSystem([Res(Nav)], (nav) => {
+ nav.setGrid(new NavGrid({
+ width: 60, // columns
+ height: 44, // rows
+ cellSize: 20, // world pixels per cell
+ origin: { x: -600, y: -440 }, // world position of cell (0,0)'s center
+ }));
+}, { name: 'SetupNav' });
+```
+
+| `NavGrid` option | Type | Description |
+|---|---|---|
+| `width` | number | Cell columns. |
+| `height` | number | Cell rows. |
+| `cellSize` | number | World pixels per cell (square). |
+| `origin` | `Vec2` | World position of cell `(0,0)`'s center. Defaults to `(0,0)`. |
+| `walkable` | `Uint8Array` | Optional row-major `width*height` mask, `1` = walkable, `0` = blocked. Omitted → all walkable. |
+
+To derive a grid from a painted tilemap instead of hand-authoring the mask, use
+`navGridFromTilemapLayer` (which cells a layer's solid tiles block) or
+`navGridFromTiles`.
+
+<Aside type="tip">
+ The `Nav` resource also answers one-off queries directly:
+ `nav.findWorldPath(from, to)` returns an array of world-space waypoints (or
+ `null` if there's no route) without needing a `NavAgent`.
+</Aside>
+
+### Moving an agent
+
+Attach a `NavAgent`, then point it at a destination. The built-in nav plugin plans
+the path and steps the agent along it each frame — you just set the goal.
+
+```typescript
+import { NavAgent, setNavDestination, stopNavAgent } from 'esengine';
+
+cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(NavAgent, { speed: 140, arriveRadius: 8 });
+
+// From any system/action with world access — safe to call every frame:
+setNavDestination(world, entity, { x: 320, y: -120 });
+// …and to halt in place:
+stopNavAgent(world, entity);
+```
+
+| `NavAgent` field | Default | Description |
+|---|---|---|
+| `speed` | `120` | Movement speed in world pixels per second. |
+| `radius` | `12` | Agent radius (arrival tolerance / collision size). |
+| `arriveRadius` | `6` | Stop distance from the final goal. |
+| `repathInterval` | `0.5` | Seconds between replans while moving; `0` = replan only when the target changes. |
+| `hasTarget` | `false` | Whether a destination is set (managed for you). |
+| `targetX`, `targetY` | `0` | Current destination in world pixels. |
+| `arrived` | `false` | Set true the frame the agent reaches its goal. |
+
+`setNavDestination` is safe to call every frame to chase a moving target — the agent
+only replans when the target actually moves or `repathInterval` elapses. Read
+`agent.arrived` (or `Perception`) to know when to switch behavior.
+
+## State machines
+
+A state machine is a set of **states** connected by guarded **transitions**. Exactly
+one state is active; each tick, its outgoing transitions are checked in order and the
+first enabled one is taken. Attach a `StateMachineAgent` and point it at a graph:
+
+```typescript
+import { StateMachineAgent } from 'esengine';
+
+cmds.spawn()
+ .insert(NavAgent, {})
+ .insert(Perceiver, { range: 240 })
+ .insert(Perception, {})
+ .insert(StateMachineAgent, { fsm: 'ai/enemy.esfsm' }); // an editor-authored asset
+```
+
+| `StateMachineAgent` field | Description |
+|---|---|
+| `fsm` | Key of the machine to run: a `registerFsm` name **or** an `.esfsm` asset path. |
+| `current` | Active state name, written each tick (read-only; visible in the inspector). |
+
+The recommended path is to **author the graph in the editor** as an `.esfsm` asset
+(see [Authoring in the editor](#authoring-in-the-editor)). The states reference your
+registered action/condition names by string. You can also build a machine in code:
+
+```typescript
+import { registerFsm } from 'esengine';
+
+registerFsm('guard', {
+ initial: 'Patrol',
+ states: [
+ {
+ name: 'Patrol',
+ onUpdate: 'patrol',
+ transitions: [{ to: 'Chase', condition: 'seesPlayer' }],
+ },
+ {
+ name: 'Chase',
+ onEnter: 'startChase',
+ onUpdate: 'chase',
+ transitions: [{ to: 'Patrol', condition: 'lostPlayer' }],
+ },
+ ],
+});
+```
+
+Each state carries up to three named hooks — `onEnter`, `onUpdate`, `onExit` — and a
+list of `transitions`. A transition is enabled when **all** of its specified
+mechanisms hold; a transition with none is unconditional:
+
+| Transition field | Description |
+|---|---|
+| `to` | Destination state name. |
+| `trigger` | A one-shot event name that must be fired (consumed when taken). |
+| `condition` | A registered condition that must return true. |
+| `guard` | One or more blackboard comparisons, AND-combined. |
+
+Guards compare a blackboard key with `==`, `!=`, `<`, `<=`, `>`, `>=`, `truthy`, or
+`falsy` — e.g. `{ key: 'health', op: '<', value: 20 }`.
+
+## Behavior trees
+
+A behavior tree ticks from its **root** every frame and returns a `Status`. Composite
+nodes control flow; decorators transform one child's result; leaves are your
+registered actions and conditions. Attach a `BehaviorTreeAgent`:
+
+```typescript
+import { BehaviorTreeAgent } from 'esengine';
+
+cmds.spawn()
+ .insert(NavAgent, {})
+ .insert(Perception, {})
+ .insert(BehaviorTreeAgent, { bt: 'ai/enemy.esbt' }); // an editor-authored asset
+```
+
+| `BehaviorTreeAgent` field | Description |
+|---|---|
+| `bt` | Key of the tree to run: a `registerBt` name **or** an `.esbt` asset path. |
+| `status` | Last root status, written each tick (read-only). |
+
+Author the tree visually in the editor, or build it in code with `registerBt`:
+
+```typescript
+import { registerBt } from 'esengine';
+
+registerBt('guard', {
+ root: {
+ type: 'selector', // try children left→right until one succeeds
+ children: [
+ {
+ type: 'sequence', // all must succeed, in order
+ children: [
+ { type: 'condition', name: 'seesPlayer' },
+ { type: 'action', name: 'chase' },
+ ],
+ },
+ { type: 'action', name: 'patrol' },
+ ],
+ },
+});
+```
+
+Node types:
+
+| Category | Type | Behavior |
+|---|---|---|
+| Composite | `sequence` | Ticks children in order; fails on the first failure, succeeds if all succeed. |
+| | `selector` | Ticks children in order; succeeds on the first success, fails if all fail. |
+| | `parallel` | Ticks all children; `policy: 'one'` succeeds when any does, `'all'` (default) when all do. |
+| Decorator | `inverter` | Inverts its child's Success/Failure. |
+| | `succeeder` | Always reports Success. |
+| | `repeater` | Re-runs its child `count` times (`0` = forever). |
+| | `wait` | Runs for `seconds` before reporting Success. |
+| Leaf | `action` | Runs the registered action `name`; its `Status` (or `Success` on void) propagates up. |
+| | `condition` | Returns `Success` when the registered condition `name` is true, else `Failure`. |
+
+## The blackboard
+
+Every FSM/BT agent owns a **`Blackboard`** — its private key/value store plus one-shot
+event triggers. Actions and conditions reach it through `ctx.blackboard`; it's how AI
+state flows between leaves and how transition guards get their values.
+
+```typescript
+registerAction('takeDamage', (ctx) => {
+ const hp = (ctx.blackboard.get<number>('health') ?? 100) - 10;
+ ctx.blackboard.set('health', hp);
+ if (hp <= 0) ctx.blackboard.fire('died'); // a transition keyed on 'died' fires once
+});
+```
+
+| Method | Description |
+|---|---|
+| `get<T>(key)` / `set(key, value)` | Read/write a value. |
+| `has(key)` / `delete(key)` | Test / remove a key. |
+| `fire(trigger)` | Fire a one-shot event; a transition keyed on it becomes enabled until taken. |
+| `isFired(trigger)` / `consume(trigger)` | Test / clear a trigger. |
+
+Blackboard values back the `guard` comparisons on FSM transitions, and the `trigger`
+mechanism is the Unity-style edge event: fired once, consumed by the transition that
+takes it.
+
+## Authoring in the editor
+
+The intended workflow is **data, not code** for the graphs themselves — you register
+the leaf logic once, then build and tune the machines/trees visually:
+
+1. In the **Content Browser**, create a **State Machine** (`.esfsm`) or **Behavior
+ Tree** (`.esbt`) asset and double-click it to open the node-graph editor.
+2. Add states/nodes, drag to connect them, and fill each leaf's **action** or
+ **condition** with one of your registered names. Set transition conditions,
+ triggers, and blackboard guards in the inspector.
+3. On the agent entity, set `StateMachineAgent.fsm` (or `BehaviorTreeAgent.bt`) to the
+ asset's path.
+
+The asset is referenced by path and **preloaded with the scene**, so the graph is
+registered before the agent first ticks — no `registerFsm`/`registerBt` call needed.
+Because both paradigms resolve leaves from the same registry, you can prototype an
+enemy as a state machine and later swap in a behavior tree (or run both) without
+touching your action/condition code.
+
+## Custom app setup
+
+The perception, FSM, BT, and navigation plugins are part of the default plugin set,
+so the **editor and the `esengine` web runtime add them for you**. Only when you build
+an app from a bare `new App()` do you add them explicitly:
+
+```typescript
+import { perceptionPlugin, fsmPlugin, btPlugin, navPlugin } from 'esengine';
+
+app.addPlugin(perceptionPlugin);
+app.addPlugin(fsmPlugin);
+app.addPlugin(btPlugin);
+app.addPlugin(navPlugin);
+```
+
+Each is exported both as a ready-to-use singleton (`navPlugin`) and as a class
+(`NavPlugin`) if you need multiple instances.
+
+## Putting it together
+
+The [`enemy-ai` example](https://github.com/esengine/estella/tree/master/examples/enemy-ai)
+hunts a player with two enemies that share the same senses and leaves — one driven by
+a state machine, the other by a behavior tree:
+
+```typescript
+import {
+ defineSystem, Res, Nav, NavGrid,
+ registerAction, registerCondition, setNavDestination, Perception,
+} from 'esengine';
+
+// Shared leaves — the same names serve BOTH the .esfsm and the .esbt.
+registerCondition('seesPlayer', (ctx) => ctx.has(Perception) && ctx.get(Perception).visible);
+registerCondition('lostPlayer', (ctx) => !ctx.has(Perception) || !ctx.get(Perception).visible);
+
+registerAction('chase', (ctx) => {
+ if (!ctx.has(Perception)) return;
+ const per = ctx.get(Perception);
+ if (per.visible) setNavDestination(ctx.world, ctx.entity, { x: per.targetX, y: per.targetY });
+});
+registerAction('patrol', () => { /* hold position until the player is seen */ });
+
+// One open nav grid over the arena.
+export const setupNavGrid = defineSystem([Res(Nav)], (nav) => {
+ nav.setGrid(new NavGrid({ width: 60, height: 44, cellSize: 20, origin: { x: -600, y: -440 } }));
+}, { name: 'SetupNavGrid' });
+```
+
+The two enemies' `StateMachineAgent.fsm` and `BehaviorTreeAgent.bt` point at
+`enemy.esfsm` / `enemy.esbt` — authored in the editor, loaded by the engine.
+Perception, the FSM/BT ticks, and nav following are all built-in, so the only game
+code is the shared leaves above plus the one-time grid.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
new file mode 100644
index 000000000..6e6de27b6
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
@@ -0,0 +1,384 @@
+---
+title: 游戏 AI
+description: 游戏 AI 层——感知、基于网格的 A* 寻路导航、状态机与行为树,全部由同一份具名动作/条件注册表驱动,并在编辑器里可视化编排。
+---
+
+import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
+
+Estella 的 AI 层把一个实体变成会**感知**、会**决策**、会**移动**的角色。它由四个协作部件
+组成,而这四者共享同一套设计:
+
+<CardGrid>
+ <Card title="感知 Perception" icon="magnifier">
+ `Perceiver` 在视野锥内感知附近的 `PerceptionTarget`,把看到的东西写进 `Perception` 组件。
+ </Card>
+ <Card title="导航 Navigation" icon="rocket">
+ `NavGrid` + A\* 寻路把 `NavAgent` 移动到任意世界坐标,并随目标移动而重新规划。
+ </Card>
+ <Card title="状态机 FSM" icon="list-format">
+ `StateMachineAgent` 运行一个 `.esfsm` 图——带进入/更新/退出钩子和带守卫的转移的状态。
+ </Card>
+ <Card title="行为树 BT" icon="puzzle">
+ `BehaviorTreeAgent` 运行一个 `.esbt` 图——选择器、序列、装饰器与叶子。
+ </Card>
+</CardGrid>
+
+统一的核心思想:**状态机和行为树是同一套构件之上的两种编排范式。** 你在代码里注册一次具名
+的*动作*与*条件*,然后把它们连进 FSM 或 BT——图在编辑器里可视化编排,而不是写死在代码里。
+感知喂给决策,决策驱动导航。
+
+<Aside type="note">
+ 这里的一切都是 `esengine` 内核里的纯 TypeScript(没有 WebAssembly 侧模块)。感知、FSM、BT、
+ 导航这四个插件都由编辑器和 Web 运行时**自动**加入。只有当你从一个裸的 `new App()` 起步时,
+ 才需要自己加插件(见[自定义应用](#自定义应用))。
+</Aside>
+
+## 共享注册表
+
+一个**动作**做某件事(追击、攻击、放个音效);一个**条件**回答一个是/否问题(我看得见玩家吗?)。
+你按名字注册一次,FSM 和 BT 都会对同一份注册表按名字解析——于是一套叶子同时服务两种范式。
+
+```typescript
+import { registerAction, registerCondition, Status, Perception, setNavDestination } from 'esengine';
+
+registerCondition('seesPlayer', (ctx) =>
+ ctx.has(Perception) && ctx.get(Perception).visible);
+
+registerAction('chase', (ctx) => {
+ const per = ctx.get(Perception);
+ setNavDestination(ctx.world, ctx.entity, { x: per.targetX, y: per.targetY });
+});
+```
+
+每个动作和条件都会收到它所运行实体的 **`AiContext`**。它和一个 `defineBehavior` 的 update
+是同一套编程模型——实体、世界、命令的访问——外加一个每个 agent 独有的 `blackboard`(黑板):
+
+| 成员 | 类型 | 说明 |
+|---|---|---|
+| `ctx.entity` | `Entity` | 该动作/条件运行所在的 agent 实体。 |
+| `ctx.dt` | `number` | 帧间隔(秒)。 |
+| `ctx.world` | `World` | 完整世界访问,用于跨实体读取。 |
+| `ctx.commands` | `Commands` | 延迟的 spawn/despawn,tick 中调用安全。 |
+| `ctx.blackboard` | `Blackboard` | 该 agent 的 AI 数据面(见[黑板](#黑板))。 |
+| `ctx.get(Comp)` | `ComponentData` | 读取**本**实体上的另一个组件。 |
+| `ctx.set(Comp, data)` | `void` | 写入**本**实体上的一个组件。 |
+| `ctx.has(Comp)` | `boolean` | 本实体是否拥有 `Comp`。 |
+
+<Aside type="tip">
+ 在模块加载时(顶层,或在一个 `Schedule.Startup` 系统里)注册你的动作和条件,好让它们在任何
+ agent 开始 tick 之前就已存在。注册表是进程级的,在多个 `App` 实例间共享。
+</Aside>
+
+### 动作的返回值
+
+**条件**总是返回 `boolean`。**动作**可以返回一个 `Status`,也可以什么都不返回:
+
+```typescript
+export enum Status { Success = 'success', Failure = 'failure', Running = 'running' }
+```
+
+- 在**行为树**里,叶子返回 `Status` 以跨帧运行(`Running`)、成功或失败。什么都不返回视为
+ `Success`。
+- 在**状态机**里,返回值被忽略——FSM 动作是一次性的副作用。
+
+写一个返回 `Status` 的动作,就能让*同一个*动作既当 BT 叶子又当 FSM 钩子。
+
+## 感知
+
+`Perceiver` 每帧扫描最近的、可见的 `PerceptionTarget`,把结果写进同一实体上的 `Perception`
+组件。决策读 `Perception`;感知只是 ECS 数据,而不是一条旁路。
+
+```typescript
+import { Perceiver, PerceptionTarget, Perception } from 'esengine';
+
+// 猎手负责感知……
+cmds.spawn()
+ .insert(Transform, { position: { x: -200, y: 0, z: 0 } })
+ .insert(Perceiver, { range: 260, fovDegrees: 120 })
+ .insert(Perception, {}); // 由感知插件每帧写入
+
+// ……任何被标记为目标的实体。
+cmds.spawn()
+ .insert(Transform, { position: { x: 100, y: 0, z: 0 } })
+ .insert(PerceptionTarget, {});
+```
+
+| 组件 | 字段 | 默认 | 说明 |
+|---|---|---|---|
+| **`Perceiver`** | `range` | `220` | 视野范围(世界像素)。 |
+| | `fovDegrees` | `360` | 视野锥角度(`360` = 全向)。 |
+| **`Perception`** | `visible` | `false` | 当前是否看见一个目标。 |
+| | `distance` | `0` | 到所见目标的距离。 |
+| | `targetX`、`targetY` | `0` | 所见目标位置(世界像素)。 |
+| | `dirX`、`dirY` | `0` | 从观察者指向目标的单位方向。 |
+| **`PerceptionTarget`** | *(标签)* | — | 把实体标记为可被 `Perceiver` 感知。 |
+
+视野锥的朝向由感知者的 `Transform` 旋转决定。`Perception` 是一个瞬态、仅运行时的组件——
+插件每帧重写它,所以你从不需要手写它的值。
+
+## 导航
+
+导航沿着一条避开被阻挡格子的路线,把 agent 移动到某个世界坐标,底层用 A\* 在一个 **`NavGrid`**
+上寻路。
+
+### 构建网格
+
+`NavGrid` 是一个由可走/被阻挡格子构成的矩形网格。把它装到 `Nav` 资源上,agent 才能对它寻路:
+
+```typescript
+import { defineSystem, Res, Nav, NavGrid } from 'esengine';
+
+export const setupNav = defineSystem([Res(Nav)], (nav) => {
+ nav.setGrid(new NavGrid({
+ width: 60, // 列数
+ height: 44, // 行数
+ cellSize: 20, // 每格的世界像素
+ origin: { x: -600, y: -440 }, // 格子 (0,0) 中心的世界坐标
+ }));
+}, { name: 'SetupNav' });
+```
+
+| `NavGrid` 选项 | 类型 | 说明 |
+|---|---|---|
+| `width` | number | 格子列数。 |
+| `height` | number | 格子行数。 |
+| `cellSize` | number | 每格的世界像素(正方形)。 |
+| `origin` | `Vec2` | 格子 `(0,0)` 中心的世界坐标。默认 `(0,0)`。 |
+| `walkable` | `Uint8Array` | 可选的行主序 `width*height` 掩码,`1` = 可走,`0` = 阻挡。省略则全部可走。 |
+
+若想从已绘制的瓦片地图推导网格,而不是手写掩码,用 `navGridFromTilemapLayer`(把某图层的
+实心瓦片视作阻挡)或 `navGridFromTiles`。
+
+<Aside type="tip">
+ `Nav` 资源也能直接回答一次性查询:`nav.findWorldPath(from, to)` 返回一组世界空间路点
+ (没有路线时返回 `null`),无需 `NavAgent`。
+</Aside>
+
+### 移动 agent
+
+加一个 `NavAgent`,然后给它指一个目的地。内置的导航插件会规划路径并每帧沿路径推进 agent——
+你只管设目标。
+
+```typescript
+import { NavAgent, setNavDestination, stopNavAgent } from 'esengine';
+
+cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(NavAgent, { speed: 140, arriveRadius: 8 });
+
+// 从任何能访问 world 的系统/动作里——每帧调用都安全:
+setNavDestination(world, entity, { x: 320, y: -120 });
+// ……以及原地停下:
+stopNavAgent(world, entity);
+```
+
+| `NavAgent` 字段 | 默认 | 说明 |
+|---|---|---|
+| `speed` | `120` | 移动速度(世界像素/秒)。 |
+| `radius` | `12` | agent 半径(到达容差 / 碰撞尺寸)。 |
+| `arriveRadius` | `6` | 距最终目标的停止距离。 |
+| `repathInterval` | `0.5` | 移动中两次重规划的间隔秒数;`0` = 只在目标改变时重规划。 |
+| `hasTarget` | `false` | 是否已设目的地(自动管理)。 |
+| `targetX`、`targetY` | `0` | 当前目的地(世界像素)。 |
+| `arrived` | `false` | agent 到达目标的那一帧被置真。 |
+
+`setNavDestination` 每帧调用都安全,可用于追一个移动的目标——只有当目标真的移动、或
+`repathInterval` 到点时,agent 才重新规划。读 `agent.arrived`(或 `Perception`)来判断何时
+切换行为。
+
+## 状态机
+
+状态机是一组由带守卫的**转移**连接起来的**状态**。任一时刻恰好一个状态处于激活;每个 tick,
+它的出边按顺序被检查,第一条满足条件的被采用。加一个 `StateMachineAgent` 并指向一个图:
+
+```typescript
+import { StateMachineAgent } from 'esengine';
+
+cmds.spawn()
+ .insert(NavAgent, {})
+ .insert(Perceiver, { range: 240 })
+ .insert(Perception, {})
+ .insert(StateMachineAgent, { fsm: 'ai/enemy.esfsm' }); // 一个编辑器编排的资产
+```
+
+| `StateMachineAgent` 字段 | 说明 |
+|---|---|
+| `fsm` | 要运行的机器的 key:一个 `registerFsm` 名字**或**一个 `.esfsm` 资产路径。 |
+| `current` | 当前激活状态名,每 tick 写入(只读;在检视面板可见)。 |
+
+推荐做法是**在编辑器里把图编排成 `.esfsm` 资产**(见[在编辑器里编排](#在编辑器里编排))。
+状态用字符串引用你注册的动作/条件名。你也可以用代码构建一台机器:
+
+```typescript
+import { registerFsm } from 'esengine';
+
+registerFsm('guard', {
+ initial: 'Patrol',
+ states: [
+ {
+ name: 'Patrol',
+ onUpdate: 'patrol',
+ transitions: [{ to: 'Chase', condition: 'seesPlayer' }],
+ },
+ {
+ name: 'Chase',
+ onEnter: 'startChase',
+ onUpdate: 'chase',
+ transitions: [{ to: 'Patrol', condition: 'lostPlayer' }],
+ },
+ ],
+});
+```
+
+每个状态最多带三个具名钩子——`onEnter`、`onUpdate`、`onExit`——以及一组 `transitions`。当一条
+转移所指定的机制**全部**成立时它才被启用;一条什么都不指定的转移是无条件的:
+
+| 转移字段 | 说明 |
+|---|---|
+| `to` | 目标状态名。 |
+| `trigger` | 必须被 fire 的一次性事件名(采用时消费)。 |
+| `condition` | 必须返回真的一个已注册条件。 |
+| `guard` | 一个或多个黑板比较,按 AND 组合。 |
+
+守卫用 `==`、`!=`、`<`、`<=`、`>`、`>=`、`truthy`、`falsy` 比较一个黑板 key——例如
+`{ key: 'health', op: '<', value: 20 }`。
+
+## 行为树
+
+行为树每帧从**根**开始 tick 并返回一个 `Status`。组合节点控制流程;装饰器变换其唯一子节点的
+结果;叶子是你注册的动作和条件。加一个 `BehaviorTreeAgent`:
+
+```typescript
+import { BehaviorTreeAgent } from 'esengine';
+
+cmds.spawn()
+ .insert(NavAgent, {})
+ .insert(Perception, {})
+ .insert(BehaviorTreeAgent, { bt: 'ai/enemy.esbt' }); // 一个编辑器编排的资产
+```
+
+| `BehaviorTreeAgent` 字段 | 说明 |
+|---|---|
+| `bt` | 要运行的树的 key:一个 `registerBt` 名字**或**一个 `.esbt` 资产路径。 |
+| `status` | 上一次根状态,每 tick 写入(只读)。 |
+
+在编辑器里可视化编排这棵树,或用 `registerBt` 用代码构建:
+
+```typescript
+import { registerBt } from 'esengine';
+
+registerBt('guard', {
+ root: {
+ type: 'selector', // 从左到右尝试子节点,直到一个成功
+ children: [
+ {
+ type: 'sequence', // 全部按序成功
+ children: [
+ { type: 'condition', name: 'seesPlayer' },
+ { type: 'action', name: 'chase' },
+ ],
+ },
+ { type: 'action', name: 'patrol' },
+ ],
+ },
+});
+```
+
+节点类型:
+
+| 类别 | 类型 | 行为 |
+|---|---|---|
+| 组合 | `sequence` | 按序 tick 子节点;第一个失败即失败,全部成功才成功。 |
+| | `selector` | 按序 tick 子节点;第一个成功即成功,全部失败才失败。 |
+| | `parallel` | tick 全部子节点;`policy: 'one'` 任一成功即成功,`'all'`(默认)全部成功才成功。 |
+| 装饰器 | `inverter` | 反转子节点的成功/失败。 |
+| | `succeeder` | 总是报告 Success。 |
+| | `repeater` | 把子节点重跑 `count` 次(`0` = 永远)。 |
+| | `wait` | 运行 `seconds` 秒后报告 Success。 |
+| 叶子 | `action` | 运行已注册动作 `name`;它的 `Status`(void 则为 `Success`)向上传播。 |
+| | `condition` | 已注册条件 `name` 为真时返回 `Success`,否则 `Failure`。 |
+
+## 黑板
+
+每个 FSM/BT agent 拥有一块 **`Blackboard`**(黑板)——它私有的键值存储加上一次性事件触发器。
+动作和条件通过 `ctx.blackboard` 访问它;这是 AI 状态在叶子间流动的方式,也是转移守卫取值的来源。
+
+```typescript
+registerAction('takeDamage', (ctx) => {
+ const hp = (ctx.blackboard.get<number>('health') ?? 100) - 10;
+ ctx.blackboard.set('health', hp);
+ if (hp <= 0) ctx.blackboard.fire('died'); // 一条以 'died' 为键的转移被 fire 一次
+});
+```
+
+| 方法 | 说明 |
+|---|---|
+| `get<T>(key)` / `set(key, value)` | 读/写一个值。 |
+| `has(key)` / `delete(key)` | 测试 / 删除一个 key。 |
+| `fire(trigger)` | fire 一个一次性事件;以它为键的转移在被采用前保持启用。 |
+| `isFired(trigger)` / `consume(trigger)` | 测试 / 清除一个触发器。 |
+
+黑板的值支撑 FSM 转移上的 `guard` 比较,而 `trigger` 机制就是 Unity 式的边事件:fire 一次,
+被采用它的那条转移消费。
+
+## 在编辑器里编排
+
+设想的工作流是图本身**用数据、不用代码**——你注册一次叶子逻辑,然后可视化地构建并调优机器/树:
+
+1. 在**内容浏览器**里,新建一个**状态机**(`.esfsm`)或**行为树**(`.esbt`)资产,双击它打开
+ 节点图编辑器。
+2. 添加状态/节点,拖拽连线,把每个叶子的**动作**或**条件**填成你注册的某个名字。在检视面板里
+ 设置转移的条件、触发器和黑板守卫。
+3. 在 agent 实体上,把 `StateMachineAgent.fsm`(或 `BehaviorTreeAgent.bt`)设为资产的路径。
+
+资产按路径引用并**随场景预加载**,所以图在 agent 首次 tick 之前就已注册——不需要
+`registerFsm`/`registerBt` 调用。因为两种范式都从同一份注册表解析叶子,你可以先把一个敌人
+原型成状态机,之后再换成行为树(或两者都跑),而不用动你的动作/条件代码。
+
+## 自定义应用
+
+感知、FSM、BT、导航这四个插件是默认插件集的一部分,所以**编辑器和 `esengine` Web 运行时会替你
+加上它们**。只有当你从一个裸的 `new App()` 构建应用时,才需要显式加:
+
+```typescript
+import { perceptionPlugin, fsmPlugin, btPlugin, navPlugin } from 'esengine';
+
+app.addPlugin(perceptionPlugin);
+app.addPlugin(fsmPlugin);
+app.addPlugin(btPlugin);
+app.addPlugin(navPlugin);
+```
+
+每个都同时导出为一个开箱即用的单例(`navPlugin`)和一个类(`NavPlugin`),需要多个实例时用类。
+
+## 组合起来
+
+[`enemy-ai` 示例](https://github.com/esengine/estella/tree/master/examples/enemy-ai)
+用两个敌人猎杀玩家,它们共享同一套感官和叶子——一个由状态机驱动,另一个由行为树驱动:
+
+```typescript
+import {
+ defineSystem, Res, Nav, NavGrid,
+ registerAction, registerCondition, setNavDestination, Perception,
+} from 'esengine';
+
+// 共享叶子——同一批名字同时服务 .esfsm 和 .esbt。
+registerCondition('seesPlayer', (ctx) => ctx.has(Perception) && ctx.get(Perception).visible);
+registerCondition('lostPlayer', (ctx) => !ctx.has(Perception) || !ctx.get(Perception).visible);
+
+registerAction('chase', (ctx) => {
+ if (!ctx.has(Perception)) return;
+ const per = ctx.get(Perception);
+ if (per.visible) setNavDestination(ctx.world, ctx.entity, { x: per.targetX, y: per.targetY });
+});
+registerAction('patrol', () => { /* 在看见玩家之前保持原地 */ });
+
+// 一张覆盖竞技场的开阔导航网格。
+export const setupNavGrid = defineSystem([Res(Nav)], (nav) => {
+ nav.setGrid(new NavGrid({ width: 60, height: 44, cellSize: 20, origin: { x: -600, y: -440 } }));
+}, { name: 'SetupNavGrid' });
+```
+
+两个敌人的 `StateMachineAgent.fsm` 和 `BehaviorTreeAgent.bt` 分别指向 `enemy.esfsm` /
+`enemy.esbt`——在编辑器里编排,由引擎加载。感知、FSM/BT 的 tick、以及跟随导航全是内置的,
+所以唯一的游戏代码就是上面的共享叶子加上那张一次性的网格。