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.

feat(aot): the compiled systems import the engine's memory, and nothing else

yhhd8998afe8874
diff --git a/compiler/tests/wasm.test.ts b/compiler/tests/wasm.test.ts
index ea92e4648..0b196f582 100644
--- a/compiler/tests/wasm.test.ts
+++ b/compiler/tests/wasm.test.ts
@@ -4,21 +4,22 @@
* @file wasm.test.ts
* @brief The emitted C, as the wasm it actually ships as.
*
- * @details Everything else compiles it natively, which is a stand-in: the target
- * the diagram puts first is Web, and two of the contract's claims are
- * only checkable on the real thing.
+ * @details Everything else compiles it natively, which is a stand-in twice over:
+ * Web is the first target on the roadmap, and two of the contract's
+ * claims can only be asked of the real artifact.
*
- * §6.5 — "the import section must be empty" — has been asserted with
- * `nm` on an object file, with a comment admitting that is as close as
- * a native build gets. `WebAssembly.Module.imports()` is the actual
- * question, and it is asked here.
+ * §6.5 — the import section must be empty — was `nm` on an object file,
+ * with a comment admitting that was as close as a native build gets.
+ * `WebAssembly.Module.imports()` is the actual question.
*
* §2.1.1 — an address is a pointer, and on wasm32 a pointer IS the
- * offset — stops being an argument here and becomes a run: the same
- * generated file, compiled by emcc, moving the same world to the same
- * bytes as the interpreter.
+ * offset — stops being an argument and becomes a run.
*
- * Skipped, loudly, where emsdk is not installed. A gate that cannot see
+ * Two shapes are built, and the second is the one that ships: a module
+ * that IMPORTS the engine's memory rather than owning one. See the
+ * block above that test for why it changes what Stage 4 costs.
+ *
+ * Skipped, loudly, where emsdk is not unpacked. A gate that cannot see
* its subject must say so rather than report green.
*/
import { describe, it, expect } from 'vitest';
@@ -42,6 +43,8 @@ const N = 24;
const FRAMES = 12;
/** Big enough for the world, small enough to stay a static array in the module. */
const IMAGE = 1 << 16;
+/** Where the world goes in an IMPORTED memory: clear of the module's own data. */
+const GUEST_BASE = 1 << 20;
/** emsdk lives in the repo, unpacked by `pnpm emsdk:setup`. */
function findEmcc(): string | null {
@@ -52,10 +55,10 @@ function findEmcc(): string | null {
const EMCC = findEmcc();
-/**
- * The module: the generated system, plus one static block for the world and a
- * way to ask where it landed. Nothing else — no runtime, no entry point.
- */
+/** Whose linear memory the module runs in. */
+type Memory = 'own' | 'imported';
+
+/** For the `own` build: one static block for the world, and where it landed. */
const SHELL_C = `/* Test scaffolding, not compiler output. */
#include "estella_abi.h"
@@ -65,33 +68,35 @@ unsigned char es_image[${IMAGE}];
unsigned int es_image_base(void) { return (unsigned int)(uintptr_t)es_image; }
`;
-/** A module that DOES import something, so the check above is not vacuous. */
+/** A module that DOES import a function, so the check below is not vacuous. */
const PROBE_C = `extern void es_probe(void);
void es_call(void) { es_probe(); }
`;
-interface Built {
- readonly bytes: Buffer;
- readonly symbol: string;
-}
-
-function build(dir: string, sys: EirSystem, layout: AbiLayout, module: Parameters<typeof emitC>[0]): Built {
+function build(dir: string, sys: EirSystem, layout: AbiLayout,
+ module: Parameters<typeof emitC>[0], memory: Memory): { bytes: Buffer; symbol: string } {
mkdirSync(dir, { recursive: true });
const c = emitC(module, layout, [sys]);
writeFileSync(join(dir, 'estella_abi.h'), c.header);
writeFileSync(join(dir, 'estella_offsets.h'), c.offsets);
writeFileSync(join(dir, 'systems.c'), c.source);
- writeFileSync(join(dir, 'shell.c'), SHELL_C);
- const out = join(dir, 'systems.wasm');
+ const sources = [join(dir, 'systems.c')];
const symbol = cSymbol(sys.name);
+ const exported = [`_${symbol}`];
+ if (memory === 'own') {
+ writeFileSync(join(dir, 'shell.c'), SHELL_C);
+ sources.push(join(dir, 'shell.c'));
+ exported.push('_es_image_base');
+ }
+ const out = join(dir, 'systems.wasm');
const built = spawnSync(EMCC!, [
...CFLAGS, '-Wall', '-Wextra',
- // A bare module: no JS glue, no entry point, and therefore nothing that
- // could quietly add an import behind the property being tested.
+ // A bare module: no JS glue and no entry point, so nothing can quietly
+ // add an import behind the property under test.
'--no-entry', '-sSTANDALONE_WASM', '-sERROR_ON_UNDEFINED_SYMBOLS=1',
- `-sEXPORTED_FUNCTIONS=_${symbol},_es_image_base`,
- '-o', out,
- join(dir, 'systems.c'), join(dir, 'shell.c'),
+ ...(memory === 'imported' ? ['-sIMPORTED_MEMORY'] : []),
+ `-sEXPORTED_FUNCTIONS=${exported.join(',')}`,
+ '-o', out, ...sources,
// emcc ships as a .bat on Windows, which needs a shell to launch.
], { encoding: 'utf8', cwd: dir, shell: process.platform === 'win32' });
if (built.status !== 0) throw new Error(`emcc failed:\n${built.stderr}`);
@@ -102,7 +107,7 @@ function build(dir: string, sys: EirSystem, layout: AbiLayout, module: Parameter
/**
* Rebuild the ctx the TS host wrote, with the image's own offsets turned into
* wasm addresses. Scaffolding: a real host materialises straight into linear
- * memory, and has no offsets to fix up.
+ * memory and has no offsets to fix up.
*/
function relocate(mem: DataView, base: number, ctx: number, plan: ReturnType<typeof planFor>): number {
const u32 = (at: number): number => mem.getUint32(at, true);
@@ -151,6 +156,38 @@ function movedWorld(layout: AbiLayout): AbiMemory {
return mem;
}
+/** Twelve frames through `run`, against the interpreter over the same world. */
+function differential(
+ layout: AbiLayout, sys: EirSystem,
+ heapOf: () => Uint8Array, base: number, viewOf: () => DataView,
+ run: (ctx: number) => void,
+): void {
+ const byInterp = movedWorld(layout);
+ const byWasm = movedWorld(layout);
+ const plan = planFor(sys);
+
+ for (let f = 0; f < FRAMES; f++) {
+ runOnAbi(sys, byInterp, layout, shipped.module.fns);
+
+ const call = materialize(byWasm, plan);
+ heapOf().set(new Uint8Array(byWasm.buffer), base);
+ run(relocate(viewOf(), base, call.ctx, plan));
+ // Back out of linear memory, so the comparison is over the world the
+ // wasm actually wrote rather than the one handed to it.
+ new Uint8Array(byWasm.buffer).set(heapOf().subarray(base, base + IMAGE));
+ flushCommands(byWasm, call);
+
+ for (let i = 1; i <= N; i++) {
+ expect(byWasm.read('Transform', i, 'position.x'), `frame ${f} entity ${i}`)
+ .toBe(byInterp.read('Transform', i, 'position.x'));
+ expect(byWasm.read('Transform', i, 'position.y'), `frame ${f} entity ${i}`)
+ .toBe(byInterp.read('Transform', i, 'position.y'));
+ }
+ }
+ expect(byWasm.read('Transform', 3, 'position.x'), 'nothing moved, so agreeing proves nothing')
+ .not.toBe(movedWorld(layout).read('Transform', 3, 'position.x'));
+}
+
describe('the emitted C as wasm', () => {
it('reports whether this gate could run at all', () => {
if (EMCC) console.log(`[wasm] built with ${EMCC}`);
@@ -165,17 +202,20 @@ describe('the emitted C as wasm', () => {
const move = shipped.module.systems.find((s) => s.name === 'MoveSystem')!;
expect(verifySystem(move, shipped.module.comps, shipped.module.fns)).toEqual([]);
const sys = inlineSystem(move, shipped.module.fns);
- const built = build(join(tmp, 'move'), sys, layout, shipped.module);
+
+ const own = build(join(tmp, 'own'), sys, layout, shipped.module, 'own');
+ const guest = build(join(tmp, 'guest'), sys, layout, shipped.module, 'imported');
+
+ const moduleOf = (b: Buffer): WebAssembly.Module =>
+ new WebAssembly.Module(b as unknown as BufferSource);
it('imports nothing at all — §6.5, asked of the wasm itself', () => {
- const imports = new WebAssembly.Module(built.bytes as unknown as BufferSource);
// Not "no imports that matter": none. The contract has no call to make,
// so the section is empty by construction rather than by trimming.
- expect(WebAssembly.Module.imports(imports)).toEqual([]);
+ expect(WebAssembly.Module.imports(moduleOf(own.bytes))).toEqual([]);
});
it('and that check has teeth: a module that DOES import one says so', () => {
- // Otherwise "no imports" could just mean the assertion cannot see any.
const dir = join(tmp, 'control');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'probe.c'), PROBE_C);
@@ -185,55 +225,57 @@ describe('the emitted C as wasm', () => {
'-sEXPORTED_FUNCTIONS=_es_call', '-o', out, join(dir, 'probe.c'),
], { encoding: 'utf8', cwd: dir, shell: process.platform === 'win32' });
expect(made.status, made.stderr).toBe(0);
- const names = WebAssembly.Module
- .imports(new WebAssembly.Module(readFileSync(out) as unknown as BufferSource))
- .map((i) => i.name);
+ const names = WebAssembly.Module.imports(moduleOf(readFileSync(out))).map((i) => i.name);
expect(names).toContain('es_probe');
});
it('exports the system, and its own memory', () => {
- const exports = WebAssembly.Module.exports(
- new WebAssembly.Module(built.bytes as unknown as BufferSource));
- const names = exports.map((e) => e.name);
- expect(names).toContain(built.symbol);
+ const names = WebAssembly.Module.exports(moduleOf(own.bytes)).map((e) => e.name);
+ expect(names).toContain(own.symbol);
expect(names).toContain('memory');
});
it('moves the world to the same bytes the interpreter does', async () => {
- const instance = await WebAssembly.instantiate(
- new WebAssembly.Module(built.bytes as unknown as BufferSource), {});
+ const instance = await WebAssembly.instantiate(moduleOf(own.bytes), {});
const api = instance.exports as unknown as {
- memory: WebAssembly.Memory;
- es_image_base: () => number;
- [k: string]: unknown;
+ memory: WebAssembly.Memory; es_image_base: () => number; [k: string]: unknown;
};
- const run = api[built.symbol] as (ctx: number) => void;
const base = api.es_image_base();
expect(base).toBeGreaterThan(0);
+ differential(layout, sys,
+ () => new Uint8Array(api.memory.buffer), base,
+ () => new DataView(api.memory.buffer),
+ api[own.symbol] as (ctx: number) => void);
+ });
- const byInterp = movedWorld(layout);
- const byWasm = movedWorld(layout);
- const plan = planFor(sys);
-
- for (let f = 0; f < FRAMES; f++) {
- runOnAbi(sys, byInterp, layout, shipped.module.fns);
-
- const call = materialize(byWasm, plan);
- const heap = new Uint8Array(api.memory.buffer);
- heap.set(new Uint8Array(byWasm.buffer), base);
- run(relocate(new DataView(api.memory.buffer), base, call.ctx, plan));
- // Back out of linear memory, so the comparison is over the world the
- // wasm actually wrote rather than the one handed to it.
- new Uint8Array(byWasm.buffer).set(heap.subarray(base, base + IMAGE));
- flushCommands(byWasm, call);
-
- for (let i = 1; i <= N; i++) {
- expect(byWasm.read('Transform', i, 'position.x'), `frame ${f} entity ${i}`)
- .toBe(byInterp.read('Transform', i, 'position.x'));
- }
- }
- expect(byWasm.read('Transform', 3, 'position.x'),
- 'nothing moved, so agreeing proves nothing')
- .not.toBe(movedWorld(layout).read('Transform', 3, 'position.x'));
+ /**
+ * The shape that ships (§6.1). A module that IMPORTS the engine's memory is
+ * in the same memory at the same offsets, so there is no boundary to
+ * rebuild: §6's warning was about a module with its OWN, which is a
+ * different thing.
+ */
+ it('a module that imports the engine memory imports NO functions', () => {
+ const imports = WebAssembly.Module.imports(moduleOf(guest.bytes));
+ expect(imports).toEqual([{ module: 'env', name: 'memory', kind: 'memory' }]);
+ expect(imports.filter((i) => i.kind === 'function')).toEqual([]);
+ expect(WebAssembly.Module.exports(moduleOf(guest.bytes)).map((e) => e.name))
+ .toContain(guest.symbol);
+ // Small enough that compiling one per project is not a build step anybody
+ // waits for — which is the whole argument for this shape.
+ expect(guest.bytes.length).toBeLessThan(4096);
+ });
+
+ it('and it moves a world that lives in memory it did not create', async () => {
+ // The engine owns this one, as it would at runtime. The module declares
+ // a minimum and a maximum for the memory it expects, and a host has to
+ // satisfy both — which is the only thing it asks of the engine.
+ const memory = new WebAssembly.Memory({ initial: 256, maximum: 256 });
+ const instance = await WebAssembly.instantiate(moduleOf(guest.bytes), { env: { memory } });
+ const api = instance.exports as unknown as Record<string, unknown>;
+ (api['_initialize'] as (() => void) | undefined)?.();
+ differential(layout, sys,
+ () => new Uint8Array(memory.buffer), GUEST_BASE,
+ () => new DataView(memory.buffer),
+ api[guest.symbol] as (ctx: number) => void);
});
});
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 642414a47..e5740bbf0 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
@@ -1,260 +1,261 @@
----
-title: 系统
-description: 用 defineSystem、Query、Res 和 Mut 声明系统。
----
-
-import { Aside } from '@astrojs/starlight/components';
-
-**系统**是每帧运行的函数。你声明它需要什么——一个组件查询,加上资源和事件——
-Estella 就会在调度中用恰好这些参数调用它。
-
-```typescript
-import {
- defineComponent, defineSystem, addSystem,
- Query, Mut, Res, Time, Transform
-} from 'esengine';
-
-const Speed = defineComponent('Speed', { value: 200 });
-
-addSystem(defineSystem(
- [Res(Time), Query(Mut(Transform), Speed)],
- (time, query) => {
- for (const [entity, transform, speed] of query) {
- transform.position.x += speed.value * time.delta;
- }
- }
-));
-```
-
-## 参数
-
-系统的第一个参数是它的**参数列表**——它将按顺序收到的数据:
-
-- **`Query(...)`** —— 遍历同时拥有列出的每个组件的实体。每次迭代产出
- `[entity, ...组件]`。
-- **`Mut(Component)`** —— 系统会写入的组件。未包裹的组件是只读的。
-- **`Res(Resource)`** / **`ResMut(Resource)`** —— 一个共享资源,只读或可写(例如提供帧计时的 `Time`)。
- `Res` 给你资源本身;`ResMut` 给你包在它外面的句柄——`.get()` / `.set(v)` / `.modify(fn)`。
-- **`Commands()`** —— 延迟的结构性改动(生成 / 销毁 / 增删组件),在下次 flush 时应用。
-- **`EventReader(E)`** / **`EventWriter(E)`** —— 读取或发送一条类型化事件流。
-
-<Aside type="caution">
- 只有当你确实要写入某个组件时才把它包进 `Mut`。只读查询让引擎可以跳过多余的变更
- 检测;而且参数表也是调度器判断「两个系统能不能换顺序」的依据——见
- [系统碰什么](#系统碰什么)。
-</Aside>
-
-## 运行顺序
-
-系统活在由**有序阶段**组成的**调度(schedule)**里。用 `addSystem` 注册进默认的
-`Update` 阶段,用 `addStartupSystem` 注册进 `Startup`(只跑一次),或用
-`addSystemToSchedule(Schedule.X, system)` 注册进任意阶段:
-
-| 阶段 | 何时运行 |
-|---|---|
-| `Startup` | 首帧之前,一次。 |
-| `First` → `PreUpdate` → `Update` → `PostUpdate` → `Last` | 每帧,按此顺序。 |
-| `FixedPreUpdate` → `FixedUpdate` → `FixedPostUpdate` | 固定步长(物理 / 复制节拍)——每帧 0..n 次。 |
-
-同一阶段内,系统**按注册顺序**运行——线性流程一个标注都不用写。再往上,按"能表达你的
-意思的最粗那一层"来选工具。
-
-### 先用阶段
-
-大多数"我要跑在它之后"其实是"我属于下一个阶段"。跨阶段的先后是固定的,不用任何依赖边:
-`PreUpdate` 收输入,`Update` 移动,`PostUpdate` 跟相机。
-
-### 排序边
-
-同一阶段内确实存在依赖时,把它写出来。依赖边按系统**名字**引用,所以要给参与排序的系统
-起名。写在 `defineSystem` 上的排序会**跟着定义走**——顶层的 `addSystem` 自身不收选项,靠
-的就是这条:
-
-```typescript
-const move = defineSystem([...], moveFn, { name: 'move' });
-const camera = defineSystem([...], cameraFn, {
- name: 'camera',
- runAfter: ['move'], // 相机跟在移动之后
-});
-
-addSystem(move);
-addSystem(camera);
-```
-
-在 **`App`** 上注册可以写同样的边,外加 `runIf`;它是在定义处已声明的边之上**追加**,而不是
-覆盖:
-
-```typescript
-import { Schedule } from 'esengine';
-
-app.addSystemToSchedule(Schedule.Update, camera, {
- runAfter: ['input'], // 叠加在上面那条 'move' 边之上
- runIf: () => isPlaying, // 条件为 false 时跳过该系统
-});
-```
-
-指向本阶段内不存在的系统的边会被忽略;依赖边一旦成环,调度器会带着成环路径抛错——
-`Circular system dependency: move → camera → move`。
-
-### 系统集(System Set)
-
-一条条给每个系统写依赖很快就烦了。`defineSystemSet` 给**一组**系统起一个名字:集合的
-`runIf` 和依赖边对每个成员生效,别的系统也只要引用这个名字就能一次约束整组。
-
-```typescript
-import { Schedule, defineSystemSet } from 'esengine';
-
-const physics = defineSystemSet('physics', {
- systems: [applyForces, integrateVelocity, resolveContacts],
- runBefore: ['render'], // 三个成员都跑在 'render' 之前
- runIf: () => !paused, // ……暂停时三个都不跑
-});
-
-app.addSystemSetToSchedule(Schedule.FixedUpdate, physics);
-
-// 一条边就等整组:
-app.addSystemToSchedule(Schedule.FixedUpdate, debugDraw, { runAfter: ['physics'] });
-```
-
-成员按列出的顺序运行。`app.addSystemSet(set)` 是注册进 `Update` 阶段的快捷方式。
-
-### 数值优先级
-
-没有 `order: 100` 这种选项,也不需要:注册顺序**就是**默认顺序,所以数值方案就是调用处
-的一次排序。
-
-```typescript
-const ordered = [
- { order: 100, system: input },
- { order: 200, system: move },
- { order: 300, system: camera },
-];
-for (const { system } of ordered.sort((a, b) => a.order - b.order)) {
- app.addSystemToSchedule(Schedule.Update, system);
-}
-```
-
-引擎不内建它,是因为数值是一份隐式的全局协议:数字会撞车,想往两者之间插入就得靠魔法
-间隔,删掉一个系统还会悄悄带走一条隐含依赖。而 `runAfter: ['move']` 陈述的是依赖本身
-——局部、可跨插件组合、且可校验。
-
-场景系统只在其所属场景处于激活状态时运行,因此多个场景可以共存于同一个世界而互不干扰。
-
-<Aside type="note">
- 顶层的 `addSystem` / `addSystemToSchedule` **不**收选项——`name` / `runBefore` /
- `runAfter` 写在 `defineSystem` 里。运行条件 `runIf` 没有定义处的写法,只能经
- `app.addSystemToSchedule(schedule, system, options)` 或所属的 `SystemSet` 施加。
-</Aside>
-
-## 过滤与变更检测
-
-查询可以在"拥有这些组件"之外进一步收窄,并对变更做出反应:
-
-```typescript
-// 额外的存在性过滤——要求/排除但不读取的组件:
-Query(Transform, Mut(Velocity)).without(Frozen).with(Enemy)
-
-// 用 filter() 做布尔组合:
-import { Query, With, Without, Or, Not } from 'esengine';
-Query(Transform).filter(Or(With(Player), With(Ally)))
-
-// 变更检测——只要该组件自本系统上次运行以来被添加/写过的实体:
-import { Query, Added, Changed } from 'esengine';
-Query(Added(Health)) // 本帧新增
-Query(Changed(Transform)) // 上次运行后被写过
-```
-
-`Removed(C)` 是它自己的查询,产出**丢失**了 `C` 的实体:
-
-```typescript
-import { defineSystem, Removed } from 'esengine';
-defineSystem([Removed(Health)], (removed) => { // Health 是你自己的组件
- for (const entity of removed) { /* 清理 */ }
-});
-```
-
-查询结果在 `for…of` 之外还有便捷方法:
-
-| 方法 | 返回 |
-|---|---|
-| `query.single()` | 唯一的匹配(否则 `null`)——用于单独的玩家/相机。 |
-| `query.count()` / `query.isEmpty()` | 匹配数 / 是否为空。 |
-| `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`,另一个下一帧读取,两者之间无直接引用。
-定义一个事件,在 app 上注册,然后把 `EventWriter` / `EventReader` 作为系统参数:
-
-```typescript
-import { defineEvent, defineSystem, EventWriter, EventReader, Commands } from 'esengine';
-
-const Damaged = defineEvent<{ entity: number; amount: number }>('Damaged');
-app.addEvent(Damaged);
-
-// 生产者:
-addSystem(defineSystem([EventWriter(Damaged)], (damaged) => {
- damaged.send({ entity: 12, amount: 5 });
-}));
-
-// 消费者(读取自上次运行以来发送的):
-addSystem(defineSystem([EventReader(Damaged), Commands()], (damaged, cmds) => {
- for (const evt of damaged) { /* evt.entity、evt.amount */ }
-}));
-```
-
-reader 可迭代,还提供 `.isEmpty()` / `.toArray()`。完整的生产者/消费者模式见
-**event-system** 示例。
+---
+title: 系统
+description: 用 defineSystem、Query、Res 和 Mut 声明系统。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**系统**是每帧运行的函数。你声明它需要什么——一个组件查询,加上资源和事件——
+Estella 就会在调度中用恰好这些参数调用它。
+
+```typescript
+import {
+ defineComponent, defineSystem, addSystem,
+ Query, Mut, Res, Time, Transform
+} from 'esengine';
+
+const Speed = defineComponent('Speed', { value: 200 });
+
+addSystem(defineSystem(
+ [Res(Time), Query(Mut(Transform), Speed)],
+ (time, query) => {
+ for (const [entity, transform, speed] of query) {
+ transform.position.x += speed.value * time.delta;
+ }
+ }
+));
+```
+
+## 参数
+
+系统的第一个参数是它的**参数列表**——它将按顺序收到的数据:
+
+- **`Query(...)`** —— 遍历同时拥有列出的每个组件的实体。每次迭代产出
+ `[entity, ...组件]`。
+- **`Mut(Component)`** —— 系统会写入的组件。未包裹的组件是只读的。
+- **`Res(Resource)`** / **`ResMut(Resource)`** —— 一个共享资源,只读或可写(例如提供帧计时的 `Time`)。
+ `Res` 给你资源本身;`ResMut` 给你包在它外面的句柄——`.get()` / `.set(v)` / `.modify(fn)`。
+- **`Commands()`** —— 延迟的结构性改动(生成 / 销毁 / 增删组件),在**声明它的那个系统返回时**
+ 应用——就在当前帧,同一帧里排在它后面的系统已经能查到这些改动。
+- **`EventReader(E)`** / **`EventWriter(E)`** —— 读取或发送一条类型化事件流。
+
+<Aside type="caution">
+ 只有当你确实要写入某个组件时才把它包进 `Mut`。只读查询让引擎可以跳过多余的变更
+ 检测;而且参数表也是调度器判断「两个系统能不能换顺序」的依据——见
+ [系统碰什么](#系统碰什么)。
+</Aside>
+
+## 运行顺序
+
+系统活在由**有序阶段**组成的**调度(schedule)**里。用 `addSystem` 注册进默认的
+`Update` 阶段,用 `addStartupSystem` 注册进 `Startup`(只跑一次),或用
+`addSystemToSchedule(Schedule.X, system)` 注册进任意阶段:
+
+| 阶段 | 何时运行 |
+|---|---|
+| `Startup` | 首帧之前,一次。 |
+| `First` → `PreUpdate` → `Update` → `PostUpdate` → `Last` | 每帧,按此顺序。 |
+| `FixedPreUpdate` → `FixedUpdate` → `FixedPostUpdate` | 固定步长(物理 / 复制节拍)——每帧 0..n 次。 |
+
+同一阶段内,系统**按注册顺序**运行——线性流程一个标注都不用写。再往上,按"能表达你的
+意思的最粗那一层"来选工具。
+
+### 先用阶段
+
+大多数"我要跑在它之后"其实是"我属于下一个阶段"。跨阶段的先后是固定的,不用任何依赖边:
+`PreUpdate` 收输入,`Update` 移动,`PostUpdate` 跟相机。
+
+### 排序边
+
+同一阶段内确实存在依赖时,把它写出来。依赖边按系统**名字**引用,所以要给参与排序的系统
+起名。写在 `defineSystem` 上的排序会**跟着定义走**——顶层的 `addSystem` 自身不收选项,靠
+的就是这条:
+
+```typescript
+const move = defineSystem([...], moveFn, { name: 'move' });
+const camera = defineSystem([...], cameraFn, {
+ name: 'camera',
+ runAfter: ['move'], // 相机跟在移动之后
+});
+
+addSystem(move);
+addSystem(camera);
+```
+
+在 **`App`** 上注册可以写同样的边,外加 `runIf`;它是在定义处已声明的边之上**追加**,而不是
+覆盖:
+
+```typescript
+import { Schedule } from 'esengine';
+
+app.addSystemToSchedule(Schedule.Update, camera, {
+ runAfter: ['input'], // 叠加在上面那条 'move' 边之上
+ runIf: () => isPlaying, // 条件为 false 时跳过该系统
+});
+```
+
+指向本阶段内不存在的系统的边会被忽略;依赖边一旦成环,调度器会带着成环路径抛错——
+`Circular system dependency: move → camera → move`。
+
+### 系统集(System Set)
+
+一条条给每个系统写依赖很快就烦了。`defineSystemSet` 给**一组**系统起一个名字:集合的
+`runIf` 和依赖边对每个成员生效,别的系统也只要引用这个名字就能一次约束整组。
+
+```typescript
+import { Schedule, defineSystemSet } from 'esengine';
+
+const physics = defineSystemSet('physics', {
+ systems: [applyForces, integrateVelocity, resolveContacts],
+ runBefore: ['render'], // 三个成员都跑在 'render' 之前
+ runIf: () => !paused, // ……暂停时三个都不跑
+});
+
+app.addSystemSetToSchedule(Schedule.FixedUpdate, physics);
+
+// 一条边就等整组:
+app.addSystemToSchedule(Schedule.FixedUpdate, debugDraw, { runAfter: ['physics'] });
+```
+
+成员按列出的顺序运行。`app.addSystemSet(set)` 是注册进 `Update` 阶段的快捷方式。
+
+### 数值优先级
+
+没有 `order: 100` 这种选项,也不需要:注册顺序**就是**默认顺序,所以数值方案就是调用处
+的一次排序。
+
+```typescript
+const ordered = [
+ { order: 100, system: input },
+ { order: 200, system: move },
+ { order: 300, system: camera },
+];
+for (const { system } of ordered.sort((a, b) => a.order - b.order)) {
+ app.addSystemToSchedule(Schedule.Update, system);
+}
+```
+
+引擎不内建它,是因为数值是一份隐式的全局协议:数字会撞车,想往两者之间插入就得靠魔法
+间隔,删掉一个系统还会悄悄带走一条隐含依赖。而 `runAfter: ['move']` 陈述的是依赖本身
+——局部、可跨插件组合、且可校验。
+
+场景系统只在其所属场景处于激活状态时运行,因此多个场景可以共存于同一个世界而互不干扰。
+
+<Aside type="note">
+ 顶层的 `addSystem` / `addSystemToSchedule` **不**收选项——`name` / `runBefore` /
+ `runAfter` 写在 `defineSystem` 里。运行条件 `runIf` 没有定义处的写法,只能经
+ `app.addSystemToSchedule(schedule, system, options)` 或所属的 `SystemSet` 施加。
+</Aside>
+
+## 过滤与变更检测
+
+查询可以在"拥有这些组件"之外进一步收窄,并对变更做出反应:
+
+```typescript
+// 额外的存在性过滤——要求/排除但不读取的组件:
+Query(Transform, Mut(Velocity)).without(Frozen).with(Enemy)
+
+// 用 filter() 做布尔组合:
+import { Query, With, Without, Or, Not } from 'esengine';
+Query(Transform).filter(Or(With(Player), With(Ally)))
+
+// 变更检测——只要该组件自本系统上次运行以来被添加/写过的实体:
+import { Query, Added, Changed } from 'esengine';
+Query(Added(Health)) // 本帧新增
+Query(Changed(Transform)) // 上次运行后被写过
+```
+
+`Removed(C)` 是它自己的查询,产出**丢失**了 `C` 的实体:
+
+```typescript
+import { defineSystem, Removed } from 'esengine';
+defineSystem([Removed(Health)], (removed) => { // Health 是你自己的组件
+ for (const entity of removed) { /* 清理 */ }
+});
+```
+
+查询结果在 `for…of` 之外还有便捷方法:
+
+| 方法 | 返回 |
+|---|---|
+| `query.single()` | 唯一的匹配(否则 `null`)——用于单独的玩家/相机。 |
+| `query.count()` / `query.isEmpty()` | 匹配数 / 是否为空。 |
+| `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`,另一个下一帧读取,两者之间无直接引用。
+定义一个事件,在 app 上注册,然后把 `EventWriter` / `EventReader` 作为系统参数:
+
+```typescript
+import { defineEvent, defineSystem, EventWriter, EventReader, Commands } from 'esengine';
+
+const Damaged = defineEvent<{ entity: number; amount: number }>('Damaged');
+app.addEvent(Damaged);
+
+// 生产者:
+addSystem(defineSystem([EventWriter(Damaged)], (damaged) => {
+ damaged.send({ entity: 12, amount: 5 });
+}));
+
+// 消费者(读取自上次运行以来发送的):
+addSystem(defineSystem([EventReader(Damaged), Commands()], (damaged, cmds) => {
+ for (const evt of damaged) { /* evt.entity、evt.amount */ }
+}));
+```
+
+reader 可迭代,还提供 `.isEmpty()` / `.toArray()`。完整的生产者/消费者模式见
+**event-system** 示例。