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: what a system touches, and how a plugin names an agent tool

esengine65cb27f982c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39872f563..34de0597f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,17 @@ published separately; it ships inside the editor.
### Added
+- **Post-processing is a declared graph, not two framebuffers.** The chain was a
+ fixed ping-pong — every pass at full resolution, each reading the one before it
+ plus the scene wired to a hard-coded unit — and the per-camera and screen-level
+ chains were two copies of that loop. A pass now declares what it reads, what it
+ writes and at what fraction of the frame; the graph culls what the image does
+ not depend on, hands out targets from a pool keyed by shape, and takes one back
+ the moment its last reader has run. A bloom chain of seven links still costs
+ two targets, because that is what the allocator does on its own for a linear
+ chain. What it unlocks is what could not be expressed before: a link at half
+ size, and a pass reading something other than its predecessor.
+
- **A shipped web build can ask for WebGPU.** Project Settings → Rendering
carries the request into `game.config.json`, and the exported host falls back
to WebGL2 wherever the browser has none — which is what makes opting in free.
@@ -68,13 +79,44 @@ published separately; it ships inside the editor.
`app.scheduleAmbiguities(schedule)` names those pairs and what they disagree
over; `app.scheduleBatches(schedule)` shows how much of a schedule is
- inherently sequential. Execution is unchanged.
+ inherently sequential.
A system that reaches through `GetWorld()` can now say what for
- (`touches: { reads, writes }`) instead of being assumed to touch everything —
- and every engine system that cannot yet says why in one line, which is the
- standing account of what separates the engine from running any of them at the
- same time.
+ (`touches: { reads, writes }`) instead of being assumed to touch everything.
+
+- **Every gameplay system says what it touches, and the answer is used.** All of
+ them took the World and declared nothing, so the analysis above reported nine
+ ambiguous pairs in the engine's own schedules — every one of them "the World
+ itself", a finding with no action attached that hid the one real collision.
+ Four of those systems could always have said (perception, nav follow, the
+ character controller, the stats overlay, which touches no component at all).
+
+ The three that genuinely run authored data — the state machine, the behaviour
+ tree, `defineBehavior` — got a way to answer rather than an excuse. A
+ registered action or condition declares its reach; `property.set` derives it
+ from the path the graph carries, since the component it writes is unknowable at
+ registration and plain in the data. A system's own `touches` may therefore be a
+ **function**, answering from the graphs actually loaded. One leaf that never
+ declared makes the whole claim `opaque` — a union that silently dropped it
+ would be a claim the scheduler trusts and the frame disproves.
+
+ Nine ambiguous pairs became one: `VelocitySystem` and `NavAgentSystem` both
+ writing Transform with nothing deciding the order. That one is now declared
+ (the order registration already produced, so nothing moves), and a test holds
+ the engine's schedules to zero.
+
+- **A system that waits no longer holds the ones it has nothing to do with.**
+ The schedule awaited each system before starting the next, so one parked on an
+ `await` stopped everything behind it. A system now starts beside an unfinished
+ one when it neither depends on it nor touches what it touches — which is the
+ declarations above being spent rather than reported.
+
+ This is concurrency, not threads: a synchronous system runs to completion the
+ moment it starts, so what overlaps is the *waiting*. Nothing in the engine is
+ async, so its own frame is unchanged; two of your async systems loading
+ different things now wait at the same time. Ordering edges still hold — a
+ `runAfter` is a stronger statement than access, and overlap requires
+ independence in the dependency graph as well.
### Fixed
@@ -97,6 +139,23 @@ published separately; it ships inside the editor.
### Changed
+- **A plugin's agent tool is named the way the wire can address it.** Enabling
+ the LDtk plugin made every message to the built-in agent fail with
+ `400 tools[101].name: string does not match pattern '^[a-zA-Z0-9_-]+$'`, and
+ nothing in that pointed at plugins: the built-in catalog is exactly 101 tools,
+ so index 101 is whatever a plugin contributed first. Two rules, each right on
+ its own — registration REQUIRED the name to start with `${pluginId}.`, plugin
+ ids are dotted, and no model endpoint accepts a dot in a tool name. They refuse
+ the whole request rather than the tool, so one plugin took the agent down with
+ it.
+
+ **Plugin authors:** a tool's name is now your plugin id with its dots folded to
+ `_`, followed by your own — plugin `acme.level-tools` registers
+ `acme_level_tools_bake-occlusion`. Letters, digits, `_` and `-` only, up to 64.
+ A tool named the old way is refused with the reason in the Output Log, and the
+ agent drops any that reach it regardless, so an old plugin can no longer take a
+ conversation with it.
+
- **A project packages without the editor.** Cooking a project and packaging it —
the asset database, the textures, atlases, audio and video, the addressable
manifest, every export target from web to Steam, and the game host a shipped
diff --git a/docs/astro/src/content/docs/core-concepts/systems.mdx b/docs/astro/src/content/docs/core-concepts/systems.mdx
index ce411c33e..dde12c7f0 100644
--- a/docs/astro/src/content/docs/core-concepts/systems.mdx
+++ b/docs/astro/src/content/docs/core-concepts/systems.mdx
@@ -45,10 +45,10 @@ in order:
- **`EventReader(E)`** / **`EventWriter(E)`** — read or send a typed event stream.
<Aside type="caution">
- Only wrap a component in `Mut` when you actually write it — read-only queries
- let the engine skip needless change-detection. (Systems run sequentially in
- schedule order; marking reads correctly is about change-tracking, not
- parallelism.)
+ Only wrap a component in `Mut` when you actually write it. Read-only queries
+ let the engine skip needless change-detection, and the parameter list is also
+ what the schedule reads to tell whether two systems can be reordered — see
+ [What a system touches](#what-a-system-touches).
</Aside>
## Running order
@@ -199,6 +199,68 @@ A query result also has convenience methods beyond `for…of`:
| `query.toArray()` | All results as an array. |
| `query.forEach((e, ...c) => …)` | Callback per match. |
+## What a system touches
+
+A system's parameter list is also its **declaration**: `Query(Mut(Transform))`
+says "I write Transform", `Res(Time)` says "I read Time". The schedule reads that
+to answer two questions — whether two systems could ever run at the same time,
+and whether the order they *do* run in was decided by anyone.
+
+`GetWorld()` is the escape hatch, and it answers neither: a system holding the
+World may touch anything, so it conflicts with everything. Where you need it,
+say what you reach for and get the answer back:
+
+```typescript
+defineSystem([GetWorld()], (world) => { /* ... */ }, {
+ name: 'Perception',
+ touches: {
+ reads: ['Perceiver', 'Transform'],
+ writes: ['Perception'],
+ },
+});
+```
+
+Components are named by string here, because the reason to reach through the
+World is usually a type registered later than the system. Three things this
+supports:
+
+- `opaque: true` — you genuinely cannot say. Different from leaving `touches`
+ out (both mean "assume everything"), but only this one says so on purpose.
+- A **function** instead of an object, re-read every time the access is. That is
+ how a system running authored data answers from what is actually loaded: the
+ state-machine system's reach is the union over the leaves the loaded `.esfsm`
+ graphs name.
+- `defineBehavior({ touches })`, for the same reason — a behaviour's body is
+ your code, and undeclared it is assumed to touch anything.
+
+### Two systems that wait
+
+Systems start in schedule order, and a synchronous one runs to completion before
+the next starts — nothing overlaps there. An **async** system is different: while
+it is parked on an `await`, the schedule may start the next system, provided that
+one neither depends on it nor touches what it touches.
+
+So two async systems loading different things wait at the same time instead of
+one after another. If you need a particular order between them, that is an
+ordering edge (`runAfter`), not something to infer from registration order.
+
+### Finding the pairs nobody ordered
+
+Two systems in one phase that touch the same data with no edge between them run
+in whatever order registration produced — so adding a third system, or moving a
+plugin in the build list, can change what your game does with nothing to point
+at. Ask:
+
+```typescript
+app.scheduleAmbiguities(Schedule.Update);
+// [{ a: 'Move', b: 'Cull', over: ['Transform'] }]
+
+app.scheduleBatches(Schedule.Update);
+// [['Move', 'Spin'], ['Cull']] — how much of the phase is inherently sequential
+```
+
+Fix one by deciding the order (`runAfter`) or by making the overlap not exist.
+
## Events
Events are a typed, decoupled message stream — one system `send`s, another reads
diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdx
index 4d250eb4c..ae78e0734 100644
--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx
@@ -364,7 +364,9 @@ agent — so if your plugin can bake occlusion, teach the agent to ask for it:
```typescript
ctx.agentTools.register({
- name: 'acme.bake-occlusion', // must start with your plugin id
+ // Your plugin id with its dots as `_` — plugin `acme.level-tools` prefixes
+ // its tools with `acme_level_tools_`.
+ name: 'acme_level_tools_bake-occlusion',
description: 'Bake occlusion for the open scene. Use after moving walls.',
schema: { type: 'object', properties: { quality: { type: 'number' } } },
effect: 'undoable',
@@ -391,10 +393,17 @@ the confirm gate behaving correctly for an honest plugin, so declare it
honestly: a tool that calls itself `journaled` while writing outside `ctx.fs`
claims a safety net that is not holding it.
-The name must be namespaced with your plugin id. An un-namespaced tool could
-shadow a built-in, and a model calling `delete_entity` believes it knows what
-happens next. A tool that breaks any of these rules is refused with the reason
-in the Output Log, rather than dropped silently.
+The name must be namespaced with your plugin id, and may contain only letters,
+digits, `_` and `-` — up to 64 of them. Both halves of that matter. An
+un-namespaced tool could shadow a built-in, and a model calling `delete_entity`
+believes it knows what happens next; a name outside the character set is one the
+model's endpoint refuses, and it refuses the whole request rather than the tool,
+which takes every conversation down with it.
+
+Plugin ids are dotted by convention and tool names cannot be, so the prefix is
+your id with its dots folded to `_`: plugin `acme.level-tools` owns the
+`acme_level_tools_` prefix. A tool that breaks any of these rules is refused
+with the reason in the Output Log, rather than dropped silently.
Whatever `run` returns is JSON-encoded for the model; throwing reports the
message as a failed call, which the model can read and act on. A tool that
diff --git a/docs/astro/src/content/docs/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/gameplay/ai/overview.mdx
index 19eca71b2..7e9a05978 100644
--- a/docs/astro/src/content/docs/gameplay/ai/overview.mdx
+++ b/docs/astro/src/content/docs/gameplay/ai/overview.mdx
@@ -79,6 +79,30 @@ is the same programming model as a [`defineBehavior`](/docs/scripting/overview/)
registry is process-wide and shared across `App` instances.
</Aside>
+### Saying what a leaf touches
+
+The system that ticks your state machines reaches for whatever its leaves reach
+for, which is knowable only once the graphs are loaded. Declare it on the
+registration and the schedule can tell that system apart from one that might
+touch anything:
+
+```typescript
+registerAction('chase', {
+ run: (ctx) => { /* ... */ },
+ touches: { reads: ['Perception'], writes: ['NavAgent'] },
+});
+
+registerCondition('seesPlayer', {
+ check: (ctx) => ctx.has(Perception) && ctx.get(Perception).visible,
+ touches: { reads: ['Perception'] },
+});
+```
+
+Optional, and worth knowing what leaving it out costs: one undeclared leaf makes
+the whole system opaque, because a union that quietly dropped it would be a
+claim the scheduler trusts and the frame disproves. See
+[What a system touches](/docs/core-concepts/systems/#what-a-system-touches).
+
### Action return values
A **condition** always returns a `boolean`. An **action** may return a `Status`
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
index 537305e29..642414a47 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
@@ -39,8 +39,9 @@ addSystem(defineSystem(
- **`EventReader(E)`** / **`EventWriter(E)`** —— 读取或发送一条类型化事件流。
<Aside type="caution">
- 只有当你确实要写入某个组件时才把它包进 `Mut`——只读查询让引擎可以跳过多余的变更
- 检测。(系统按调度顺序**串行**运行;正确标注只读是为了变更追踪,不是为了并行。)
+ 只有当你确实要写入某个组件时才把它包进 `Mut`。只读查询让引擎可以跳过多余的变更
+ 检测;而且参数表也是调度器判断「两个系统能不能换顺序」的依据——见
+ [系统碰什么](#系统碰什么)。
</Aside>
## 运行顺序
@@ -181,6 +182,58 @@ defineSystem([Removed(Health)], (removed) => { // Health 是你自己的组件
| `query.toArray()` | 所有结果组成数组。 |
| `query.forEach((e, ...c) => …)` | 每个匹配调用一次回调。 |
+## 系统碰什么
+
+系统的参数表同时也是它的**声明**:`Query(Mut(Transform))` 说的是「我写 Transform」,
+`Res(Time)` 说的是「我读 Time」。调度器读这份声明来回答两个问题——两个系统有没有可能
+同时跑,以及它们**实际**的先后顺序是不是有人决定过。
+
+`GetWorld()` 是逃生舱,这两个问题它都答不了:握着整个 World 的系统可能碰任何东西,
+所以它和**所有**系统冲突。确实需要它的地方,把你伸手够的东西说出来,答案就回来了:
+
+```typescript
+defineSystem([GetWorld()], (world) => { /* ... */ }, {
+ name: 'Perception',
+ touches: {
+ reads: ['Perceiver', 'Transform'],
+ writes: ['Perception'],
+ },
+});
+```
+
+这里组件用**字符串**指名,因为要走 World 的理由通常正是「这个类型注册得比系统晚」。
+它支持三件事:
+
+- `opaque: true` —— 你**确实**说不出来。这和干脆不写 `touches` 效果相同(都按「碰一切」
+ 处理),区别是这一种是**明说的**。
+- 传**函数**而不是对象,每次读取访问信息时都会重新问一遍。跑「用户编写的数据」的系统
+ 靠它回答:状态机系统够到的东西,是已加载的 `.esfsm` 图里那些叶子的并集。
+- `defineBehavior({ touches })`,同样的道理——行为体是你的代码,不声明就按碰一切处理。
+
+### 两个要等待的系统
+
+系统按调度顺序**启动**,而同步系统一启动就跑到底,下一个才开始——这中间没有任何重叠。
+**async** 系统不一样:当它挂在 `await` 上时,调度器可以启动下一个系统,**前提是**后者
+既不依赖它、也不碰它碰的东西。
+
+于是两个加载不同东西的 async 系统是**同时**在等,而不是一个等完另一个再等。如果你需要
+它们之间有确定的先后,那是一条顺序边(`runAfter`),不是从注册顺序里推出来的东西。
+
+### 找出没人定过顺序的那些对
+
+同一阶段里两个系统碰同一份数据、之间又没有边,它们的先后就是注册顺序碰巧产生的——于是
+加进第三个系统、或者在构建列表里挪一下插件,游戏行为就变了,而且没有任何地方能指。问它:
+
+```typescript
+app.scheduleAmbiguities(Schedule.Update);
+// [{ a: 'Move', b: 'Cull', over: ['Transform'] }]
+
+app.scheduleBatches(Schedule.Update);
+// [['Move', 'Spin'], ['Cull']] —— 这个阶段有多少是天然串行的
+```
+
+修法是二选一:把顺序定下来(`runAfter`),或者让这个重叠根本不存在。
+
## 事件
事件是一条类型化、解耦的消息流——一个系统 `send`,另一个下一帧读取,两者之间无直接引用。
diff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
index 9ce7fa0ec..6b1d2fcf6 100644
--- a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
@@ -335,7 +335,9 @@ ctx.assets.registerImporter({
```typescript
ctx.agentTools.register({
- name: 'acme.bake-occlusion', // 必须以你的插件 id 开头
+ // 你的插件 id,点号换成 `_`——插件 `acme.level-tools` 的工具都以
+ // `acme_level_tools_` 开头。
+ name: 'acme_level_tools_bake-occlusion',
description: '为当前场景烘焙遮蔽。移动过墙体之后使用。',
schema: { type: 'object', properties: { quality: { type: 'number' } } },
effect: 'undoable',
@@ -349,7 +351,9 @@ ctx.agentTools.register({
**没有任何东西会去核实这个字段**,而这不是漏洞——你的插件本来就握着整个编辑器接口,同样的事它用一个命令也能做。边界在安装时的信任提示,不在这个字段。这个字段换来的是:对一个诚实的插件,确认门能正确工作。所以请如实声明——一个自称 `journaled` 却绕开 `ctx.fs` 去写盘的工具,是在宣称一张并没有接住它的安全网。
-名字必须以你的插件 id 开头。不带命名空间的工具可能**盖住内置工具**,而模型在调 `delete_entity` 时是相信自己知道会发生什么的。违反上述任一条的工具会被**拒绝并在输出日志里说明原因**,不会被静默丢掉。
+名字必须以你的插件 id 开头,且**只能含字母、数字、`_` 和 `-`,最多 64 个**。两半都要紧:不带命名空间的工具可能**盖住内置工具**,而模型在调 `delete_entity` 时是相信自己知道会发生什么的;而字符集之外的名字模型端点根本不收——它拒的是**整个请求**而不是那一个工具,于是这一个工具会把每一次对话都带下水。
+
+插件 id 按惯例带点号,而工具名不能带,所以前缀是**你的 id 把点号折成 `_`**:插件 `acme.level-tools` 拥有 `acme_level_tools_` 这个前缀。违反上述任一条的工具会被**拒绝并在输出日志里说明原因**,不会被静默丢掉。
`run` 返回什么就 JSON 编码给模型;抛出异常会作为一次失败调用上报,消息模型读得到、也能据此调整。对话进行中出现的新工具会加入**下一次**对话——工具列表排在提示词最前面,中途变更会让它之后的每一个缓存字节作废。
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx
index 2078049df..39a377819 100644
--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx
@@ -70,6 +70,27 @@ registerAction('chase', (ctx) => {
agent 开始 tick 之前就已存在。注册表是进程级的,在多个 `App` 实例间共享。
</Aside>
+### 声明一个叶子碰什么
+
+跑你的状态机的那个系统,够到的东西就是它的**叶子**够到的东西——而这只有在图加载之后才
+知道。在注册时声明出来,调度器就能把这个系统和「可能碰任何东西」的系统区分开:
+
+```typescript
+registerAction('chase', {
+ run: (ctx) => { /* ... */ },
+ touches: { reads: ['Perception'], writes: ['NavAgent'] },
+});
+
+registerCondition('seesPlayer', {
+ check: (ctx) => ctx.has(Perception) && ctx.get(Perception).visible,
+ touches: { reads: ['Perception'] },
+});
+```
+
+可选,但值得知道不写的代价:**只要有一个叶子没声明,整个系统就退回「碰一切」**——因为
+一份悄悄丢掉了读不懂那部分的并集,是一个调度器会信、而帧会推翻的声明。参见
+[系统碰什么](/docs/zh-cn/core-concepts/systems/#系统碰什么)。
+
### 动作的返回值
**条件**总是返回 `boolean`。**动作**可以返回一个 `Status`,也可以什么都不返回: