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.

docs: Scripting (defineBehavior) guide (en + zh)

esengineab102ca04f5f
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 238dfb9af..7f66400ea 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -49,6 +49,7 @@ export default defineConfig({
label: 'Gameplay',
translations: { 'zh-CN': '玩法' },
items: [
+ { label: 'Scripting', translations: { 'zh-CN': '脚本' }, slug: 'guides/scripting' },
{ label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'guides/camera' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdx
index d81293b77..9adfda56c 100644
--- a/docs/astro/src/content/docs/guides/ai.mdx
+++ b/docs/astro/src/content/docs/guides/ai.mdx
@@ -59,8 +59,8 @@ registerAction('chase', (ctx) => {
```
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`:
+is the same programming model as a [`defineBehavior`](/docs/guides/scripting/) update
+— entity, world, and commands access — plus a per-agent `blackboard`:
| Member | Type | Description |
|---|---|---|
diff --git a/docs/astro/src/content/docs/guides/scripting.mdx b/docs/astro/src/content/docs/guides/scripting.mdx
new file mode 100644
index 000000000..f510e5abb
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/scripting.mdx
@@ -0,0 +1,181 @@
+---
+title: Scripting
+description: Write per-entity game logic with defineBehavior — one call gives you an editor-tunable component plus a start/update/destroy lifecycle, desugared entirely onto the ECS with no second runtime.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`defineBehavior` is the authoring sugar for the gameplay loop. One call gives you two
+things at once:
+
+1. A **component** that holds this behavior's per-entity `state` — attachable to any
+ entity and tunable in the editor's Details panel.
+2. An auto-registered **system** that drives a `start` / `update` / `destroy`
+ lifecycle for every entity carrying that component.
+
+There is no second scripting runtime: a behavior desugars entirely onto Estella's
+existing [ECS](/docs/core-concepts/ecs/) — the same components, systems, and
+scheduling you already use — so it stays fast and fully inspectable.
+
+## Your first behavior
+
+`defineBehavior(name, def)` returns the backing component, so you can spawn or insert
+it like any other. The `state` object becomes the component's per-entity data:
+
+```typescript
+import { defineBehavior, Transform } from 'esengine';
+
+export const Patrol = defineBehavior('Patrol', {
+ state: { speed: 60 }, // per-entity data, editable in the Details panel
+ update(ctx, dt) {
+ ctx.get(Transform).position.x += ctx.self.speed * dt;
+ },
+});
+```
+
+That single call registers the update system. To put the behavior on an entity, insert
+its component — optionally overriding the starting `state`:
+
+```typescript
+import { defineSystem, Commands, Transform } from 'esengine';
+
+const spawn = defineSystem([Commands()], (cmds) => {
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(Patrol, { speed: 120 }); // override the default per instance
+});
+```
+
+<Aside type="tip">
+ Because a behavior *is* a component, you can also attach it in the editor — drag it
+ onto an entity in the **Details** panel and tune `speed` there. Code and editor are
+ two doors to the same data.
+</Aside>
+
+## The lifecycle
+
+Each hook is optional; define only the ones you need.
+
+| Hook | When it runs |
+|---|---|
+| `start(ctx)` | Once, the frame the behavior's component first appears on an entity. |
+| `update(ctx, dt)` | Every frame, for each entity carrying the behavior. `dt` is the frame delta in seconds (same as `ctx.time.delta`). |
+| `destroy(ctx)` | Once when the component is removed **or** the entity is despawned. |
+
+```typescript
+export const Enemy = defineBehavior('Enemy', {
+ state: { hp: 100 },
+ start(ctx) {
+ // one-time setup: seed state, cache lookups, spawn a health bar…
+ },
+ update(ctx, dt) {
+ if (ctx.self.hp <= 0) ctx.commands.despawn(ctx.entity);
+ },
+ destroy(ctx) {
+ // teardown: runs whether the entity was killed or the component was detached
+ },
+});
+```
+
+<Aside type="note">
+ `destroy` is driven by entity **presence**, not a per-frame flag: it fires the frame
+ an entity drops out of the behavior's query, whichever system removed it and in
+ whatever order. That makes cleanup order-independent and reliable.
+</Aside>
+
+## The context
+
+Every hook receives a `BehaviorContext` — the handle to the entity it runs for and to
+the world around it:
+
+| Member | Type | Description |
+|---|---|---|
+| `ctx.self` | `S` | This behavior's own `state`. **Mutate it freely — changes persist.** |
+| `ctx.entity` | `Entity` | The entity this instance is attached to. |
+| `ctx.time` | `TimeData` | Frame timing: `delta`, `elapsed`, `frameCount`, `fixedDelta`. |
+| `ctx.input` | `InputState` | Keyboard / mouse / touch / gamepad (see [Input](/docs/guides/input/)). |
+| `ctx.commands` | `Commands` | Deferred spawn / despawn / insert — safe to call mid-update. |
+| `ctx.world` | `World` | Full world access for cross-entity reads and writes. |
+| `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`. |
+
+```typescript
+import { defineBehavior, Transform } from 'esengine';
+
+export const PlayerController = defineBehavior('PlayerController', {
+ state: { speed: 200, facing: 1 },
+ update(ctx, dt) {
+ const move = (ctx.input.isKeyDown('KeyD') ? 1 : 0) - (ctx.input.isKeyDown('KeyA') ? 1 : 0);
+ if (move !== 0) ctx.self.facing = move; // mutating self persists
+ ctx.get(Transform).position.x += move * ctx.self.speed * dt;
+ },
+});
+```
+
+<Aside type="caution">
+ The `ctx` object is **reused** across entities and frames for zero per-entity
+ allocation. Read from it inside the hook, but never stash it (or its
+ `self`/`time`/`input`) in a closure or array to use later — copy the values you need.
+</Aside>
+
+## Editable state & metadata
+
+The `state` object defines the component's fields and their defaults. Pass `metadata`
+to control how those fields present in the editor — ranges, steps, units, enums — the
+same field metadata any [component](/docs/core-concepts/components/) uses:
+
+```typescript
+export const Turret = defineBehavior('Turret', {
+ state: { range: 300, fireRate: 2, target: 0 },
+ metadata: {
+ fields: {
+ range: { min: 0, unit: 'px', category: 'Targeting' },
+ fireRate: { min: 0, unit: '/s', category: 'Targeting', tooltip: 'Shots per second.' },
+ },
+ },
+ update(ctx, dt) { /* … */ },
+});
+```
+
+Because the state is a real serialized component, per-entity overrides are saved with
+the scene and edited live in the Details panel.
+
+## Choosing a schedule
+
+By default the lifecycle system runs in `Schedule.Update`, once per frame. Pass a
+different `schedule` to run elsewhere in the frame — for example
+`Schedule.FixedUpdate` to advance in lockstep with physics:
+
+```typescript
+import { defineBehavior, Schedule } from 'esengine';
+
+export const Thruster = defineBehavior('Thruster', {
+ schedule: Schedule.FixedUpdate,
+ state: { force: 500 },
+ update(ctx) {
+ // fixed cadence — read ctx.time.fixedDelta for the fixed step
+ },
+});
+```
+
+Available phases include `Startup`, `PreUpdate`, `Update`, `PostUpdate`, and the fixed
+trio `FixedPreUpdate` / `FixedUpdate` / `FixedPostUpdate`.
+
+## How it fits together
+
+A behavior is not a special case — it compiles to exactly one `defineComponent` plus
+one `defineSystem`. Reach for `defineBehavior` when your logic is naturally
+*per-entity* (a patrol, a projectile, a pickup); reach for a plain
+[system](/docs/core-concepts/systems/) when you're processing a whole query at once or
+coordinating across entities.
+
+The hook signature — `entity`, `world`, `commands`, plus `self` — is also the same
+programming model used by the [Gameplay AI](/docs/guides/ai/) layer's actions and
+behavior-tree leaves, so moving logic between a behavior and an AI action is
+straightforward.
+
+<Aside type="note">
+ On hot reload, per-entity `start` runs again for live entities — matching Estella's
+ fast-restart semantics, so treat `start` as idempotent setup.
+</Aside>
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 6e6de27b6..4c4446c6d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
@@ -50,8 +50,9 @@ registerAction('chase', (ctx) => {
});
```
-每个动作和条件都会收到它所运行实体的 **`AiContext`**。它和一个 `defineBehavior` 的 update
-是同一套编程模型——实体、世界、命令的访问——外加一个每个 agent 独有的 `blackboard`(黑板):
+每个动作和条件都会收到它所运行实体的 **`AiContext`**。它和一个
+[`defineBehavior`](/docs/zh-cn/guides/scripting/) 的 update 是同一套编程模型——实体、世界、
+命令的访问——外加一个每个 agent 独有的 `blackboard`(黑板):
| 成员 | 类型 | 说明 |
|---|---|---|
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx b/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
new file mode 100644
index 000000000..25da15f19
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
@@ -0,0 +1,166 @@
+---
+title: 脚本
+description: 用 defineBehavior 编写每实体的游戏逻辑——一次调用同时给你一个编辑器可调的组件和 start/update/destroy 生命周期,完全降解到 ECS 之上,没有第二套运行时。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`defineBehavior` 是游戏循环的编排糖。一次调用同时给你两样东西:
+
+1. 一个**组件**,持有这个行为的每实体 `state`——可挂到任意实体,并在编辑器 Details 面板里调。
+2. 一个自动注册的**系统**,为每个携带该组件的实体驱动 `start` / `update` / `destroy` 生命周期。
+
+这里没有第二套脚本运行时:一个 behavior 完全降解到 Estella 现有的
+[ECS](/docs/zh-cn/core-concepts/ecs/) 之上——还是你已经在用的那套组件、系统和调度——所以它
+既快又完全可检视。
+
+## 你的第一个 behavior
+
+`defineBehavior(name, def)` 返回其背后的组件,所以你能像任何组件一样 spawn 或 insert 它。
+`state` 对象成为该组件的每实体数据:
+
+```typescript
+import { defineBehavior, Transform } from 'esengine';
+
+export const Patrol = defineBehavior('Patrol', {
+ state: { speed: 60 }, // 每实体数据,可在 Details 面板里编辑
+ update(ctx, dt) {
+ ctx.get(Transform).position.x += ctx.self.speed * dt;
+ },
+});
+```
+
+这一次调用就注册了更新系统。要把行为放到实体上,insert 它的组件——还能顺便覆盖起始 `state`:
+
+```typescript
+import { defineSystem, Commands, Transform } from 'esengine';
+
+const spawn = defineSystem([Commands()], (cmds) => {
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(Patrol, { speed: 120 }); // 每个实例单独覆盖默认值
+});
+```
+
+<Aside type="tip">
+ 因为一个 behavior *就是*一个组件,你也能在编辑器里挂它——在 **Details** 面板里把它拖到某个
+ 实体上,在那里调 `speed`。代码和编辑器是通往同一份数据的两扇门。
+</Aside>
+
+## 生命周期
+
+每个钩子都是可选的;只定义你需要的那些。
+
+| 钩子 | 何时运行 |
+|---|---|
+| `start(ctx)` | 一次,在该行为的组件首次出现在某实体上的那一帧。 |
+| `update(ctx, dt)` | 每帧,对每个携带该行为的实体。`dt` 是帧间隔(秒)(等同 `ctx.time.delta`)。 |
+| `destroy(ctx)` | 一次,当组件被移除**或**实体被 despawn 时。 |
+
+```typescript
+export const Enemy = defineBehavior('Enemy', {
+ state: { hp: 100 },
+ start(ctx) {
+ // 一次性初始化:播种状态、缓存查找、生成血条……
+ },
+ update(ctx, dt) {
+ if (ctx.self.hp <= 0) ctx.commands.despawn(ctx.entity);
+ },
+ destroy(ctx) {
+ // 收尾:不管实体是被杀死还是组件被卸下,都会运行
+ },
+});
+```
+
+<Aside type="note">
+ `destroy` 由实体的**存在性**驱动,而不是每帧的标志位:它在实体掉出该行为查询的那一帧触发,
+ 不论是哪个系统移除了它、以什么顺序。这让清理与顺序无关且可靠。
+</Aside>
+
+## 上下文
+
+每个钩子都会收到一个 `BehaviorContext`——通往它所运行实体、以及周围世界的句柄:
+
+| 成员 | 类型 | 说明 |
+|---|---|---|
+| `ctx.self` | `S` | 该行为自己的 `state`。**随意改——修改会持久化。** |
+| `ctx.entity` | `Entity` | 该实例所挂的实体。 |
+| `ctx.time` | `TimeData` | 帧计时:`delta`、`elapsed`、`frameCount`、`fixedDelta`。 |
+| `ctx.input` | `InputState` | 键盘 / 鼠标 / 触摸 / 手柄(见 [输入](/docs/zh-cn/guides/input/))。 |
+| `ctx.commands` | `Commands` | 延迟的 spawn / despawn / insert——update 中调用安全。 |
+| `ctx.world` | `World` | 完整世界访问,用于跨实体读写。 |
+| `ctx.get(Comp)` | `ComponentData` | 读取**本**实体上的另一个组件。 |
+| `ctx.set(Comp, data)` | `void` | 写入**本**实体上的一个组件。 |
+| `ctx.has(Comp)` | `boolean` | 本实体是否拥有 `Comp`。 |
+
+```typescript
+import { defineBehavior, Transform } from 'esengine';
+
+export const PlayerController = defineBehavior('PlayerController', {
+ state: { speed: 200, facing: 1 },
+ update(ctx, dt) {
+ const move = (ctx.input.isKeyDown('KeyD') ? 1 : 0) - (ctx.input.isKeyDown('KeyA') ? 1 : 0);
+ if (move !== 0) ctx.self.facing = move; // 改 self 会持久化
+ ctx.get(Transform).position.x += move * ctx.self.speed * dt;
+ },
+});
+```
+
+<Aside type="caution">
+ `ctx` 对象在实体与帧之间**被复用**,以实现每实体零分配。在钩子内部读它,但绝不要把它(或它的
+ `self`/`time`/`input`)存进闭包或数组留着以后用——把你需要的值拷出来。
+</Aside>
+
+## 可编辑状态与元数据
+
+`state` 对象定义了组件的字段和默认值。传 `metadata` 来控制这些字段在编辑器里的呈现——范围、
+步进、单位、枚举——和任何[组件](/docs/zh-cn/core-concepts/components/)用的字段元数据是同一套:
+
+```typescript
+export const Turret = defineBehavior('Turret', {
+ state: { range: 300, fireRate: 2, target: 0 },
+ metadata: {
+ fields: {
+ range: { min: 0, unit: 'px', category: 'Targeting' },
+ fireRate: { min: 0, unit: '/s', category: 'Targeting', tooltip: 'Shots per second.' },
+ },
+ },
+ update(ctx, dt) { /* … */ },
+});
+```
+
+因为状态是一个真正的、可序列化的组件,每实体的覆盖值会随场景保存,并在 Details 面板里实时编辑。
+
+## 选择调度
+
+默认情况下生命周期系统在 `Schedule.Update` 里运行,每帧一次。传一个不同的 `schedule` 可以在帧
+里的别处运行——例如用 `Schedule.FixedUpdate` 与物理同步推进:
+
+```typescript
+import { defineBehavior, Schedule } from 'esengine';
+
+export const Thruster = defineBehavior('Thruster', {
+ schedule: Schedule.FixedUpdate,
+ state: { force: 500 },
+ update(ctx) {
+ // 固定节奏——读 ctx.time.fixedDelta 拿到固定步长
+ },
+});
+```
+
+可用的相位包括 `Startup`、`PreUpdate`、`Update`、`PostUpdate`,以及固定三件套
+`FixedPreUpdate` / `FixedUpdate` / `FixedPostUpdate`。
+
+## 它如何组合
+
+一个 behavior 并不是特例——它编译成恰好一个 `defineComponent` 加一个 `defineSystem`。当你的逻辑
+天然是*每实体*的(巡逻、抛射物、拾取物)时,用 `defineBehavior`;当你要一次处理整个查询、或在实体
+间协调时,用一个普通[系统](/docs/zh-cn/core-concepts/systems/)。
+
+钩子签名——`entity`、`world`、`commands`,外加 `self`——也和[游戏 AI](/docs/zh-cn/guides/ai/) 层
+的动作与行为树叶子是同一套编程模型,所以在 behavior 和 AI 动作之间搬逻辑很顺手。
+
+<Aside type="note">
+ 热重载时,存活实体的 `start` 会再跑一次——契合 Estella 的快速重启语义,所以把 `start` 当作
+ 幂等的初始化来写。
+</Aside>