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
docs: what a system touches, and how a plugin names an agent tool
esengine65cb27f982c6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 → Renderingcarries the request into `game.config.json`, and the exported host falls backto 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 disagreeover; `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 addressablemanifest, every export target from web to Steam, and the game host a shippeddiff --git a/docs/astro/src/content/docs/core-concepts/systems.mdx b/docs/astro/src/content/docs/core-concepts/systems.mdxindex 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.+## EventsEvents are a typed, decoupled message stream — one system `send`s, another readsdiff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdxindex 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:```typescriptctx.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 ithonestly: 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 themessage as a failed call, which the model can read and act on. A tool thatdiff --git a/docs/astro/src/content/docs/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/gameplay/ai/overview.mdxindex 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 valuesA **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.mdxindex 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.mdxindex 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({```typescriptctx.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.mdxindex 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`,也可以什么都不返回: