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.
变更观测契约(Mutation Observation Contract)
目标读者:引擎维护者 / AI 协作代理。 本文记录 PR6c 第一刀的普查结果:引擎当前允许哪些写法改变 World、其中哪些 ChangeTracker 观测得到、以及把读接口收紧成只读要付多少迁移成本。 本文不改任何实现,它是拍板前的证据。
0. 问题
bench/replication-dirty/ 的四臂实验(PR6b)在性能上给了 N1 一个可用的答案,但它的
completeness probe 顺手证伪了一个前提:合法代码拿到脚本组件的 live reference 后原地写,
shadow scan 看得见,ChangeTracker 看不见。 只要还有一条这样的路径,ChangeTracker 就不能
充当权威的 candidate 来源——那部分状态会直接停止复制,而且没有任何地方会说一声。
所以在测 crossover 之前,先要回答的是语义问题,而不是性能问题:
引擎的「读」接口和「写」接口,边界到底在哪?
1. 两台机器
| 机器 | 问什么 | 怎么跑 |
|---|---|---|
tools/mutation-contract.mjs |
每条访问路径实际上做了什么:值真的变了吗?tracker 看到了吗? | node tools/mutation-contract.mjs |
tools/mutation-census.mjs |
这个仓库实际上有多少代码在通过读句柄写 | node tools/mutation-census.mjs |
两台都对自己做过标定:
- contract fixture 被三次 sabotage 验证过:让
tryGet返回拷贝、让tryGet记 changed、 让Mut写回不再报告——每次都只红在它守的那几行,撤掉即回绿。 第二次 sabotage 顺带暴露了 fixture 自己的一个洞:snapshot()经由tryGet读,而它排在 observed 计算之前,读若有副作用就会污染判决。已改成先问 observed 再取快照。 - census 有
--self-test:它声称能识别的每种形态都写成正样本并断言命中数, 所以「零发现」永远不可能被误读成「仓库很干净」。标定过程中抓到过它自己两个缺陷:Object.assign被同时记成 write 和 escape;以及 alias 链上的写回没被识别 (const p = t.position; p.x = 1; world.set(e, T, t)被误判为静默写—— multiplayer-arena 的移动函数正是这个形状)。
2. 运行时契约:18 条路径的实测
node tools/mutation-contract.mjs,wasm 与 SDK 均为当前 HEAD 构建:
| 访问路径 | 值真的变了 | tracker 看到 | 判定 |
|---|---|---|---|
world.set / insert / remove |
是 | 是 | 已报告 |
world.set(嵌套 shape / builtin) |
是 | 是 | 已报告 |
world.markChanged |
否 | 是 | 已报告 |
Query(Mut(C)) 写回(脚本 / builtin) |
是 | 是 | 已报告 |
world.get(e,C).f = v(脚本) |
是 | 否 | 静默写 |
world.tryGet(e,C).f = v(脚本) |
是 | 否 | 静默写 |
world.get/tryGet(e,C).nested.x = v(脚本) |
是 | 否 | 静默写 |
裸 Query(C) 行写入(脚本,两种 shape) |
是 | 否 | 静默写 |
| 句柄跨 tick 持有后再写 | 是 | 否 | 静默写 |
world.get/tryGet(e,C).nested.x = v(builtin) |
否 | 否 | 惰性(写被丢弃) |
裸 Query(C) 行写入(builtin) |
否 | 否 | 惰性(写被丢弃) |
18 条路径,7 条是静默写。
三个必须记下来的事实:
脚本组件的两种存储都是 live 的。 全 scalar 的 shape 被
ScriptStorage池化成 wasm 堆 视图,带嵌套对象的 shape 是普通 JS 对象——两者get/tryGet/裸Query交出去的都是 存储里那个对象本身,写它就是写 World。PR6b 只证过池化那一种。同一个 API 在 builtin 上是另一种错法。
get/tryGet对 builtin 返回一次性投影, 写它既不改 World 也不报告——不是「安全」,是静默丢弃。裸Query(C)对 builtin 更糟:resolvePtrGetter返回的是一个跨行复用的 scratch 对象,写入会被下一行的 fill 覆盖。 于是同一行代码row.field = v在脚本组件上悄悄改了世界,在 builtin 上悄悄什么都没做。PR6c.2 已修这一格的读侧。 那不只是写侧的陷阱:
toArray()曾把三行返回成同一个 对象、值全等于最后一行,纯读也是错的。现在forEach是明确的 borrowed 快路, iterator /single/toArray交出可保留的行;代价是每行一次分配 (脚本组件 1.2x,引擎组件 1.7x)。判据见sdk/tests/query-row-lifetime.test.ts。Query的文档承诺没有被执行层兑现。 文档写的是「除非包在Mut里否则只读」, 但裸Query(C)的 getter 对脚本组件就是storage.get(e)。承诺只存在于类型注释里。
3. 用量普查:收紧类型要付多少
node tools/mutation-census.mjs,扫描 1694 个文件(sdk/src、sdk/tests、examples、
desktop/src,编辑器子模块经其自身索引读取):
280 处经由读句柄的写
237 处是「读—改—写回」(后面跟着 set/insert/markChanged,今天就正常报告)
43 处是静默写(值变了,没有任何人观测到)
109 处句柄逃逸出本普查的视野(传进了别的函数)
这两个数字回答的是两个不同的问题,不能混用:
- 43 是今天就存在的缺陷数量。
- 280 是把
get/tryGet/裸Query收成DeepReadonly的迁移面—— 因为那 237 处合法的读—改—写回同样是在写一个读句柄,类型收紧会一并挡住。
43 处静默写的分布
| 位置 | 处数 | 性质 |
|---|---|---|
sdk/src/ui/text/text-input-plugin.ts |
15 | 引擎自身 |
sdk/src/ui/input/drag.ts |
12 | 引擎自身 |
sdk/tests/* |
13 | 测试固化了这个语义 |
examples/celestial-heights/src/systems/combat.ts |
3 | flagship 游戏的伤害结算 |
三处定罪:
world.test.ts有一个 describe 块就叫component data mutations,其中两个用例名为should allow mutating component data和should reflect mutations immediately,直接断言world.get(...).x = 100之后值确实变了。scene.test.ts更直白,注释写着 “Mutate the LIVE component”。这不是无意的疏漏,是有测试背书的既有公开语义—— 收紧类型是推翻它,不是补上一个未定义行为。text-input-plugin.ts写了 8 次ti.dirty = true,而TextInputData.dirty全仓零读者。 这是同一个问题的化石:有人需要「这个组件变了」这个信号,而经world.get原地写不会让 tracker 报告,于是他在组件里自己加了一个 dirty 字段——然后这个字段从来没有被读过一次。damageSystem的血量结算完全静默:world.get(target, Health)之后health.current -= blow.amount,没有任何写回。任何Changed(Health)消费者或 Health 的复制都收不到它。 同一目录下layout.ts正在用world.anyChangedSince(UINode, ...)决定要不要重算布局—— 同一个 tracker,一边被当权威,一边被绕过。
3.5 PR6c.3:world.update 与静默写归零
裁定已执行第一步。新增 world.update(entity, Component, draft => {…}),它是「读出来、改一个字段、
其余保留」的唯一写入口:
- 脚本组件零拷贝——draft 就是存储里那个对象,编辑后
recordChanged; - 引擎组件读投影、编辑、经
set写回(hierarchy 也走它),不发明第三套机制; - 无条件报告:不做深比较。假阳性让消费者多看一眼,而按比较决定会在它读不懂的值上变哑;
edit抛异常不回滚:脚本组件上已经写进去的就是写进去了,所以在异常逃逸前先报告—— 一个没人听见的半写正是这条路要消灭的东西;- draft 是借用的,不许留存。
43 处静默写已清到 0,其中:
| 位置 | 处数 | 做法 |
|---|---|---|
text-input-plugin.ts |
15 | 7 处改 update;8 处 ti.dirty = true 直接删 |
drag.ts |
12 | 全部改 update |
sdk/tests/* |
13 | 改走合法路径;三个假 World 补上 update(假实现落后于真实现正是它骗人的方式) |
combat.ts |
3 | 伤害结算改 update |
TextInputData.dirty 全仓零读者,是变更观测缺位时长出来的私有 dirty 机制化石。写入已删,
字段本身标 @deprecated 留到下一个 MINOR——顶层未知字段在反序列化时是错误,
立刻删字段会让存量场景加载失败。
mutation-census 已升级成门禁(--gate,注册为 silent-writes):静默写恒为 0。
它对扫不到的 root(未检出的编辑器子模块)明说而不是静默缩小语料。
3.6 PR6c.4:Mut → Changed 在三条执行路上都成立
这一节没有新建判据——证据早就在仓库里,只是没人认领它证明了什么。
Query(Mut(C)) |
值 | Changed |
|---|---|---|
| JS 解释执行 | ✓ | ✓ |
| Web AOT(编译进 wasm) | ✓ | ✓ |
| Native AOT(打包宿主) | ✓ | ✓ |
两条编译路各有独立的实现权威,所以各有独立的证据,不能互相背书:
- Web:
sdk/tests/aot-conformance.test.ts是真编译(compiler → C →emcc→ wasm), 末尾挂一个解释执行的Query(Changed(Mover))watcher,逐帧比较两条路的ticks, 并断言ticks.some(n => n > 0)(watcher 匹配不到任何东西时两条路也会一致)。 实现在AotDispatch.markChanged_,按 packed rows 标记。 - Native:
tools/verify-native-conformance.mjs把打包宿主CONF行里的ticked列 与解释器写下的trace.json.ticks逐帧比较。实现是另一个markChanged_(installNativeAot.ts),它在 native call 返回后重新查询匹配实体,而不是回传 packed rows。
两次 sabotage 都做过:分别删掉两个 markChanged_ 调用,两条 conformance 各自变红,
且都红在 ticks(frame 1:0 vs 4),而值与资源的比较仍然相等——
证明这条 conformance 确实由变更观测这一职责撑住,且这个职责在 world 的值里看不见。
契约是「只有声明为 Mut 的 projection 产生观测」,不是「AOT 跑过的都变 dirty」。
两条 AOT 路都从同一份 manifest 声明里取 mutated 集合,而这条规则钉在
sdk/tests/query.test.ts 的 Query(Mut(A), B) → A Changed / B not。
顺带修掉一个假绿机器:runtime template 内嵌 SDK 的 QuickJS 字节码,所以改了 SDK 却不
重建 template,native conformance 就在对着旧引擎报绿——sabotage 第一次跑正是这样通过的。
判据现在先查 sdk/src → sdk/dist → template 这条链,陈旧就报 did NOT run(exit 2)。
(.generated.ts 不计入,原生构建会在打包之后重写它们。)
3.7 PR6d:removal 历史有主了
cleanRemovedBuffer 是一个没有归属权的全局 destructive API,而且它有一个调用者:
App.tick 每帧末尾 cleanRemovedBuffer(worldTick - 2)。所以这不是内存问题,是正确性缺陷——
任何超过 2 帧没运行的 Removed(C) system(runIf 关着、FixedUpdate 没到步、条件系统)
会静默丢失它本该看到的 removal。判据 sdk/tests/removed-retention.test.ts 第一条先红在这里。
现在是 per-component 的 reader watermark:
ChangeTracker
├─ 变更观测:Added / Changed / anyChangedSince ← trackedComponents_
└─ removal 历史:每 component 一张 reader 表 ← removedReaders_
readerId → retainFromTick,prune 到最低的那个
- watermark 按 component 分,不是全局:一个组件的慢 reader 没有资格钉住另一个组件的历史。
- cursor 在
flushSystem_推进,不在resetTick——system 可以await到一半, 在 body 读之前就宣告「读完了」,会让另一个 reader 的 prune 删掉它仍然欠着的行。 - 认领发生在参数提交之后,不在构造函数里:一组参数中途抛异常时, 已经建好的那个 reader 没有任何人能释放它,那个 component 的历史从此永久被钉住。
evict()/reset()真的 dispose:丢掉 JS 引用不等于放弃认领。- 没有 reader 就不产生 removal 行。
Changed(C)需要知道拓扑动了 (componentLastChangedTick_照常更新,UI 布局依赖它),但不需要知道谁在 tick 738 掉了 C。 于是「开着 Changed(C)、没有 Removed(C)、despawn 十万次」从十万行变成 0 行。 - 历史从 reader 认领的那一刻开始(
retainFromTick = worldTick + 1), 新 reader 不认领别人碰巧留下的古老 removal。
慢的活着的 reader 钉住历史不是 bug——Removed 的语义就是「自这个 system 上次运行以来」。
真正的 bug 是已经 evict 掉的 reader 还在钉,所以 ownership 才必须显式。
八条判据,六次 sabotage 各红一条:把 release 挪到 body 之前/改成全局 watermark/
evict 不 dispose/reset 不 dispose/在构造函数里认领/让任何 tracked 组件都写 removal 行。
World.cleanRemovedBuffer 已删——一个谁都能替别人删历史的接缝,在有了归属权之后没有位置。
4. 待裁定
普查给出的结论是明确的:get/tryGet/裸 Query 必须收成只读,而且必须是
DeepReadonly 而不是浅 Readonly(c.nested.x = 1 这条路径已实测为静默写)。
但 280 这个数字意味着不能只收紧类型。237 处读—改—写回是今天合法且报告正常的写法,
把它们全部改成「自己复制整个组件再 set」既是无谓的迁移,也会让热路径多一次拷贝。
所以收紧读接口必须与一个符合人体工学的单实体写接口同时落地
(world.update(e, C, draft => {...}) 之类),否则这一刀会把成本转嫁给所有调用方。
同时未判定、留给后续的两件:
AOT 写回:已实测,见 3.6。:已收掉,见 3.7。cleanRemovedBuffer的归属权