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(systems): document ordering, filtering/change-detection, and events (en + zh-cn)
yhh3d4bd58a2a01
diff --git a/docs/astro/src/content/docs/core-concepts/systems.mdx b/docs/astro/src/content/docs/core-concepts/systems.mdxindex a38595f3a..33c57c543 100644--- a/docs/astro/src/content/docs/core-concepts/systems.mdx+++ b/docs/astro/src/content/docs/core-concepts/systems.mdx@@ -36,7 +36,11 @@ in order:iteration yields `[entity, ...components]`.- **`Mut(Component)`** — a component the system writes. Unwrapped components areread-only.-- **`Res(Resource)`** — a shared resource, such as `Time` for frame timing.+- **`Res(Resource)`** / **`ResMut(Resource)`** — a shared resource, read-only or+ writable (such as `Time` for frame timing).+- **`Commands()`** — deferred structural changes (spawn / despawn / add / remove),+ applied at the next flush.+- **`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@@ -47,6 +51,101 @@ in order:## Running order-Systems are organized by a **schedule**. Register a system with `addSystem`, or-add it through a plugin on your `App`. Scene systems only run while their scene-is active, so multiple scenes can coexist in one world without interfering.+Systems live in a **schedule** of ordered phases. Register into the default+`Update` phase with `addSystem`, into `Startup` (runs once) with `addStartupSystem`,+or into any phase with `addSystemToSchedule(Schedule.X, system)`:++| Phase | When it runs |+|---|---|+| `Startup` | Once, before the first frame. |+| `First` → `PreUpdate` → `Update` → `PostUpdate` → `Last` | Every frame, in this order. |+| `FixedPreUpdate` → `FixedUpdate` → `FixedPostUpdate` | On the fixed timestep (physics / replication cadence) — 0..n times per frame. |++Within a phase, systems run in registration order. To constrain that, register on+the **`App`** with ordering options — these reference system **names**, so name the+systems you want to order:++```typescript+import { Schedule } from 'esengine';++const move = defineSystem([...], moveFn, { name: 'move' });+const camera = defineSystem([...], cameraFn, { name: 'camera' });++app.addSystemToSchedule(Schedule.Update, move);+app.addSystemToSchedule(Schedule.Update, camera, {+ runAfter: ['move'], // camera follows movement+ runIf: () => isPlaying, // skip this system when the condition is false+});+```++Scene systems only run while their scene is active, so multiple scenes can coexist+in one world without interfering.++<Aside type="note">+ The top-level `addSystem` / `addSystemToSchedule` take **no** options, and+ `defineSystem`'s options keep only `name` — so ordering (`runBefore` / `runAfter`+ / `runIf`) is applied through `app.addSystemToSchedule(schedule, system, options)`.+</Aside>++## Filtering & change detection++A query can narrow beyond "has these components" and react to changes:++```typescript+// Extra presence filters — components you require/exclude but don't read:+Query(Transform, Mut(Velocity)).without(Frozen).with(Enemy)++// Boolean combinations via filter():+import { Query, With, Without, Or, Not } from 'esengine';+Query(Transform).filter(Or(With(Player), With(Ally)))++// Change detection — only entities whose component was added/changed since+// this system last ran:+import { Query, Added, Changed } from 'esengine';+Query(Added(Health)) // newly-added this frame+Query(Changed(Transform)) // written since the last run+```++`Removed(C)` is its own query that yields entities that **lost** `C`:++```typescript+import { defineSystem, Removed, Health } from 'esengine';+defineSystem([Removed(Health)], (removed) => {+ for (const entity of removed) { /* cleanup */ }+});+```++A query result also has convenience methods beyond `for…of`:++| Method | Returns |+|---|---|+| `query.single()` | The one match (or `null`) — for a lone player/camera. |+| `query.count()` / `query.isEmpty()` | Match count / whether empty. |+| `query.toArray()` | All results as an array. |+| `query.forEach((e, ...c) => …)` | Callback per match. |++## Events++Events are a typed, decoupled message stream — one system `send`s, another reads+next frame, with no direct reference between them. Define an event, register it on+the app, then take an `EventWriter` / `EventReader` as a system parameter:++```typescript+import { defineEvent, defineSystem, EventWriter, EventReader, Commands } from 'esengine';++const Damaged = defineEvent<{ entity: number; amount: number }>('Damaged');+app.addEvent(Damaged);++// Producer:+addSystem(defineSystem([EventWriter(Damaged)], (damaged) => {+ damaged.send({ entity: 12, amount: 5 });+}));++// Consumer (reads what was sent since it last ran):+addSystem(defineSystem([EventReader(Damaged), Commands()], (damaged, cmds) => {+ for (const evt of damaged) { /* evt.entity, evt.amount */ }+}));+```++A reader is iterable and also offers `.isEmpty()` / `.toArray()`. See the+**event-system** example for the full producer/consumer pattern.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 0a5c4b81c..2ca700fde 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@@ -33,7 +33,9 @@ addSystem(defineSystem(- **`Query(...)`** —— 遍历同时拥有列出的每个组件的实体。每次迭代产出`[entity, ...组件]`。- **`Mut(Component)`** —— 系统会写入的组件。未包裹的组件是只读的。-- **`Res(Resource)`** —— 一个共享资源,例如提供帧计时的 `Time`。+- **`Res(Resource)`** / **`ResMut(Resource)`** —— 一个共享资源,只读或可写(例如提供帧计时的 `Time`)。+- **`Commands()`** —— 延迟的结构性改动(生成 / 销毁 / 增删组件),在下次 flush 时应用。+- **`EventReader(E)`** / **`EventWriter(E)`** —— 读取或发送一条类型化事件流。<Aside type="caution">只有当你确实要写入某个组件时才把它包进 `Mut`——只读查询让引擎可以跳过多余的变更@@ -42,6 +44,97 @@ addSystem(defineSystem(## 运行顺序-系统由**调度(schedule)**组织。用 `addSystem` 注册一个系统,或通过 `App` 上的插件-加入它。场景系统只在其所属场景处于激活状态时运行,因此多个场景可以共存于同一个世界-而互不干扰。+系统活在由**有序阶段**组成的**调度(schedule)**里。用 `addSystem` 注册进默认的+`Update` 阶段,用 `addStartupSystem` 注册进 `Startup`(只跑一次),或用+`addSystemToSchedule(Schedule.X, system)` 注册进任意阶段:++| 阶段 | 何时运行 |+|---|---|+| `Startup` | 首帧之前,一次。 |+| `First` → `PreUpdate` → `Update` → `PostUpdate` → `Last` | 每帧,按此顺序。 |+| `FixedPreUpdate` → `FixedUpdate` → `FixedPostUpdate` | 固定步长(物理 / 复制节拍)——每帧 0..n 次。 |++同一阶段内,系统按注册顺序运行。要约束顺序,在 **`App`** 上带排序选项注册——它们按系统+**名字**引用,所以给要排序的系统起名:++```typescript+import { Schedule } from 'esengine';++const move = defineSystem([...], moveFn, { name: 'move' });+const camera = defineSystem([...], cameraFn, { name: 'camera' });++app.addSystemToSchedule(Schedule.Update, move);+app.addSystemToSchedule(Schedule.Update, camera, {+ runAfter: ['move'], // 相机跟在移动之后+ runIf: () => isPlaying, // 条件为 false 时跳过该系统+});+```++场景系统只在其所属场景处于激活状态时运行,因此多个场景可以共存于同一个世界而互不干扰。++<Aside type="note">+ 顶层的 `addSystem` / `addSystemToSchedule` **不**收选项,`defineSystem` 的选项只保留+ `name`——所以排序(`runBefore` / `runAfter` / `runIf`)要经+ `app.addSystemToSchedule(schedule, system, options)` 施加。+</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, Health } from 'esengine';+defineSystem([Removed(Health)], (removed) => {+ for (const entity of removed) { /* 清理 */ }+});+```++查询结果在 `for…of` 之外还有便捷方法:++| 方法 | 返回 |+|---|---|+| `query.single()` | 唯一的匹配(否则 `null`)——用于单独的玩家/相机。 |+| `query.count()` / `query.isEmpty()` | 匹配数 / 是否为空。 |+| `query.toArray()` | 所有结果组成数组。 |+| `query.forEach((e, ...c) => …)` | 每个匹配调用一次回调。 |++## 事件++事件是一条类型化、解耦的消息流——一个系统 `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** 示例。