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.

chore(docs): the roadmap moves to docs/local, which is not tracked

yhh9f5fc1cc7715
diff --git a/.gitignore b/.gitignore
index 4e8ea2103..57f71f95c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -127,6 +127,12 @@ __pycache__/
docs/REARCH_*.md
docs/REARCH_*.html
+# Local-only working docs. Anything in here stays on this machine: planning,
+# competitive teardowns, notes naming third-party projects. Put a doc here when
+# it must NOT reach the public remote — the whole directory is ignored, so a
+# `git add -A` cannot pick it up by accident.
+docs/local/
+
# Editor-local workspace cache (last scene, panel layout) — never commit
**/.esengine/workspace.json
diff --git a/desktop b/desktop
index f0d4546ee..40835a590 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit f0d4546ee669bf1e02619a0c140d955b909df70b
+Subproject commit 40835a590b83d2b6c5f69569619c459744a8a0c0
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
deleted file mode 100644
index 5fb8adde0..000000000
--- a/docs/ROADMAP.md
+++ /dev/null
@@ -1,314 +0,0 @@
-# Estella Roadmap
-
-> 状态基线:0.58.0(2026-08-27)。这份文件只写**从 CHANGELOG 和提交信息里读不出来的东西**:
-> 下一步做什么、为什么是它、以及「做完了」长什么样。逐条改了什么在 CHANGELOG 里。
->
-> `docs/REARCH_*.md` 是 gitignore 的,活不过一次 clone;这份是 tracked 的,所以放在这里。
-
-## 现在站在哪
-
-- **AOT 三条路都通了**:web、小游戏、桌面 native。桌面打包的游戏把标了 `@compiled` 的
- 系统当机器码跑,`bench/aot-native/frame-bench.mjs --gate` 让它成为发布准则。
-- **无 JIT 的帧第一次被量到**:5,000 实体、一个做三次乘加的系统,**51 ms 解释 → 1.7 ms 编译**,
- 解释器代价在真实帧上是 **61x**(不是裸循环的 154–385x)。
-- **3D 地基收口**:render graph 拥有 scene pass、depth 可采样、`render.meshes/triangles/culled`
- 有计数、三条 `*-scale-cost` 有天花板。
-- **`examples/celestial-heights/engine-gaps.mjs` 是空的** —— 旗舰游戏没有一处在绕开引擎。
-- **子系统定级**:28 个里 6 个 `public`、12 个 `beta`、10 个 `experimental`,
- 而且「凭什么可以升」现在有机器判了(`check-tier-bar`)。
-
-## 1. 编译系统的代价正比于「世界」,不是「它匹配的集合」(前半已落地)
-
-**证据。** `native/host/bindings/AotBindings.cpp` 里,每帧、每个编译系统,`es_aot_run`
-用 `forEachEntity` 把**所有活实体**推进候选表,`aot::run` 再对每一个解析每个组件。
-量到的:同样 5,000 个 mover,世界 5,000 时 0.114 ms,世界 50,000 时 0.333 ms —— **2.9x**,
-约 4.9 ns/帧/它根本不碰的实体。解释侧是对照组,几乎不动(49.3 → 51.2 ms),因为 SDK 的
-query 会收窄。20k 实体、一个匹配 200 的系统 → 96% 的工作是空转,第二个编译系统再扫一遍。
-
-**为什么它排第一。** 这是唯一一处「编译这条路在某个维度上比解释还差」的地方,而且它随
-游戏变大而变糟 —— 正好是 AOT 存在的场景。两处修都不是编译器改动,都在同一个进程里。
-
-**两条 AOT 路要回答的是同一组问题,而 native 这条一个也没答。** `AotDispatch.ts`
-(web)的文件头把模型写死了:**一张 row table 是两件事的函数 —— 哪些实体匹配,以及它们的
-组件在哪。** 每一件都有一个已经能便宜回答的权威。web 那条路两个都用上了(query cache 的
-数组身份 + `World.layoutEpoch`),native 那条路两个都没用 —— 它每帧重扫世界、重打全表。
-所以这不是给 native 加一个优化,是把它补齐到 web 已有的那个形状。
-
-**做什么。**
-
-1. **哪些实体匹配 —— 用最短的那一列收窄候选。**〔已落地〕`AotHost::run` 的注释一直写着
- 「caller passes the smallest pool it has」,而 native 这个 caller 从来没做到。
- `Registry::entitiesWith<T>()` 把 `View` 内部一直在用的「取最小池」这件事开成一扇门
- (`View` 拿的是类型,AOT 宿主拿的是名字,所以必须在运行期问);发
- `AotComponents.generated.*` 的那个 generator 顺手发出第二张表。
- script 组件那半需要池自己的 dense 面 —— `ScriptPool` 的 slot 是复用不压缩的,所以
- slot→entity 的表天然就是它,代价是每次 put/delete 一次 O(1) 写。**这一半是必须的**:
- bench 里的 `Mover` 是项目组件,只收窄引擎池什么也买不到。
-
-2. **组件在哪 —— 跨帧复用 row table。**〔已落地 2026-08-27〕两条路现在回答同一组问题。
-
- **实测(100,000 个 mover,同一构建开关缓存)**:打表的代价在这台宿主上约
- **3.4 ns/entity** —— thin 从 11.4 降到 8.0 ns/entity,heavy 从 14.6 降到 12.5。
- **不是 web 那条路的 27.5 → 不到 2**:那边打表是 JS 逐实体逐组件解析地址,这边是 C++,
- 便宜一个数量级。**在一个宿主上量到的结论不能照搬到另一个。**
-
- **下面这条是开工前必须知道的,也是这次真正的收获。**
- `Registry::layoutEpoch()` 是「地址有没有动」的权威,**不是「谁匹配」的权威** ——
- `SparseSet::emplace` 只在 `components_` 真的 realloc 时才 `++version_`(容量内追加不
- 动已发出的指针,所以不需要 bump)。也就是说**往池里加一个实体可以完全不动 epoch**。
- web 那条路正是因此用了**两个**条件,不是一个。native 侧的对应物:
- - 「谁匹配」= 收窄后那一列的 `(data(), size())` 身份。引擎侧够用:容量内 emplace 会让
- `size()` 变,realloc 会让 `data()` 变或让 epoch 变,`remove`/`clear`/`sort` 无条件
- bump epoch。
- - **script 列不够用。** 删一个 slot 不改 `rows`/`sparse`/`ownerCount`(`next_` 不回退),
- 只在 owners 数组里留一个洞 —— 宿主看到的 span 逐字节同一个。所以 script 那半需要
- `ScriptStorage.layoutEpoch` 真的过界,World 上要开一扇 `scriptLayoutEpoch()`,
- `es_aot_run` 要多收一个参数。
- - 引擎侧的 epoch **不需要**过界:native 宿主就在同一个进程里,直接
- `host().registry->layoutEpoch()`(web 那条路当年还得为此加 embind 绑定)。
-
- **两个条件而不是一个**,落地时就是按这个写的:epoch 管「地址动没动」,而每个 query
- 点名的**每一列**都按身份盯着 —— 不只是最短的那一列,因为 query 是在所有列上匹配的,
- 而变的那一列未必就是它收窄用的那一列。两个条件都做过双向 sabotage。
-
-**前半的结果(`8379ba9f3`,2026-08-27)。** 同机实测:20,000 个 mover 在
-200,000 实体的世界里,系统自身代价 **0.43 ms**,与「世界里只有它自己」的 0.51 ms 无异;
-收窄前是 1.29 ms。
-
-**门禁不是时钟,是计数。** 原计划是「小世界/大世界的每实体代价比值」,实测行不通:
-idle 相减的 run-to-run 抖动是 ±0.3 ms,而答案本身只有 0.4 ms —— 同一个构建的小世界测了
-0.226 ms,重测得 −0.015 ms。修好与修坏在 200,000 实体世界里是 1.45 ms vs 2.31 ms,
-1.6x,噪声够得着。所以宿主改为发布一个**计数** `aotCandidates`(`native/host/Bench.hpp`),
-`frame-bench --gate` 断言 `walked <= ENTITIES * 1.5`:20,000 对 200,001,精确、无容差。
-双向 sabotage 验过。**先找那个计数器,再去找更好的时钟。**
-
-顺带修掉一个它翻出来的 bug:`installNativeAot` 把实体索引掩码自己拼成了 20 位(真值 22 位),
-世界超过 2^20 实体时一个脚本组件会读到**另一个实体的行**。
-
-## 2. AOT 还没到它本来为之而生的平台
-
-**事实。** 拿到 AOT 的是**有 JIT** 的桌面;iOS 和 Android 全解释。这是 2026-08-26
-「桌面优先」明确接受的代价(桌面宿主是我们的、能 `dlopen`、导出机就是目标机),但它是
-这条路唯一的战略缺口。
-
-**Android 先。** NDK 是个下载,不需要 Apple 硬件;`tools/verify-native-boot.mjs
---platform android` 已经是发布准则,设备那条路已经通了。做的事不是新概念:
-`compiler/src/hostCC.ts` 的 seam 从「找宿主编译器」扩成「按 target triple 选编译器」,
-`compileTargetFor` 已经是「问宿主要哪条路」的形状,链接标志和模块扩展名那张表也已经在。
-
-**两个已知会咬人的地方**(都是已经付过一次学费的):MSVC 那次说明「导出什么符号」是每个
-平台各自的事(`ES_EXPORT` 要按 NDK 再验一次);`LoadLibrary` 那次说明「库从哪里找」也是。
-
-**开工前要定的一件事:iOS 的产物形状。** 桌面走 `dlopen` 一个 `.dll`/`.so`。iOS 上模块
-要签名并嵌进 app bundle,导出机必须是 Mac。如果最终形状是「导出产出一个 `.a`,宿主重新
-链接」,那 `hostCC` 现在就该按**两种产物**设计,而不是等到 iOS 那步再拆已经绿的桌面路。
-
-**完成的样子。** Android 版的 `verify-aot-native`:「N installed」**和**
-「\<name\> is running compiled」两个都要,跟桌面同一个准则 —— installed 不够,一个模块
-可以加载成功然后永远不被 dispatch 到。
-
-**这台机器上开不了工〔2026-08-27 实测〕。** `requireNdk`
-(`build-tools/utils/android.js:33`)在没有 `ANDROID_NDK_HOME` / `ANDROID_NDK_ROOT`,
-也没有 `$ANDROID_HOME/ndk` 时直接抛错,而这台机器两者都没有 —— `adb` 是独立装的
-platform-tools,不是完整 SDK。**注意编译那一半才是被卡住的**:设备是连着的
-(`adb devices` 看得到 `bd56533d`),所以验证那一半现成可用。
-
-**所以这是一个要你决定的岔路**:装 NDK(Android Studio 的 SDK Manager,或解压一份并
-设 `ANDROID_NDK_HOME`),还是把第 2 项挪到别的机器上做。在那之前它开不了。
-
-## 3. 一帧花了多少**时间**,没有任何东西给它天花板〔已落地 2026-08-27〕
-
-**现状。** 计数天花板有(`sprite-scale-cost` / `mesh-scale-cost` / `shadow-scale-cost`)。
-时间的没有:`tools/perf-guard.mjs` 断言的是微基准之间的**比值**(CPU 抵消掉),
-`tools/perf-budget.mjs` 断言的是 50k 资产工程上**操作**的上限。两个都不看渲染的一帧。
-
-**形状:同机比值,不是毫秒。** 跟 AOT 那个门禁同一个理由 —— 毫秒天花板在别人的机器上
-要么松到抓不住东西,要么随机红。
-
-### 开工前必须知道的:像素门禁那个宿主没有一把够用的尺子(2026-08-27 实测)
-
-原本的打算是「像素门禁 runner 已经是个 harness,只缺一个时间的门」。**不成立** ——
-缺的是时钟,不是门。
-
-- **web 侧 `FrameProfiler` 读的是 `emscripten_get_now()` → `performance.now()`**
- (`src/esengine/core/FrameProfiler.hpp:29`),Chromium 在**没有跨源隔离**时把它钳到
- 100 µs。后果不是「不够准」,是**两个 scope 一直读作 0**:无头跑一帧,`render.submit`
- 和 `render.graph` 都是 `0.000`,而 `render.collect` 是 `0.400`、`render.finalize`
- 是 `0.200` —— 全是 0.1 的整数倍。
-- **给 render host 的服务器加 COOP/COEP 能解钳**,实测同一场景变成 `render.submit=0.0100`、
- `render.graph=0.0150`(约 5 µs,细 20 倍)。**但它同时把 GPU 计时器关掉**:`gpuMs` 从
- `0.055296` 变成 `-1`。两个方向都量过,是确定性的。
-- **`gpuMs` 本来就不可靠**:小阴影场景答 0.055,4225 个网格的 `scale-meshes` 上
- **不加隔离也是 -1**。
-- 今天没有任何门禁消费 `ESTELLA_VERIFY_PROFILE`,所以这个取舍没有现成的消费者来决定 ——
- 那次 COOP/COEP 改动因此被撤回了:拿一个能用的 GPU 计时器去换一个没人读的 CPU 分辨率,
- 不划算。
-
-**所以结论变了:时间预算不该建在 web 那个宿主上。** 引擎已经有一个**能用的**帧时钟 ——
-在 native 宿主上(`native/host/Bench.hpp` + `WebGPUDevice::setPresentUncapped`),而且
-已经被 AOT 那条发布准则用着(`bench/aot-native/frame-bench.mjs --gate`)。要给一帧上时间
-预算,从那里开始,而不是再造一把尺子。
-
-**顺带还欠一个分母**:阴影图集的图块数对光源数。`shadow-scale-cost` 曾经带过
-`render.shadow.tiles` 的上限,被拿掉了,因为那个场景里没有任何东西能把它推过 8 ——
-它由 cascade 数界定,不由 caster 数界定。要预算它得换一个分母。
-
-### 落地了什么(2026-08-27)
-
-**新准则 `a-frame-pays-for-what-it-draws`**,由 `frame-bench --gate` 回答。形状是一对:
-同一个场景两份,只差实体身上有没有 `Sprite`。两半装着同样的实体、跑同样的调度,所以机器
-和引擎自己那份每帧开销都在分母里,只有分子扛着「画」。实测 128,000 个 sprite 让一帧变成
-「只装着它们」那一帧的 **3.65–4.21x**,59–61 ns/sprite。
-
-**实体数是用来让比值*稳*的,不是用来让它*大*的。** 分母是小的那个数,它的抖动就是比值的
-抖动:32,000 上分母在几次运行间读出 1.03 和 1.19 ms,健康比值散在 2.85–3.01,而破坏读
-3.90 —— **重叠了,天花板 4 抓不住它**。128,000 上分子重复到 1%,同一个破坏(每个 sprite
-提交两次)把 59 ns/sprite 变成 115、比值变成 6.97,对天花板 5 两次都红,三次健康跑全绿。
-
-**开工前先撞了两堵墙,都不在计划里,而且都让「已有的钟」根本没在走。**
-
-1. **三条发布准则在 Mac 上从来跑不了,其中一条还把 runner 的错说成引擎的错。**
- `verify-aot-native` 和 frame-bench 都靠「找一个没有扩展名的文件」定位刚导出的 app,
- 而每个签过名的 macOS bundle 都带 `Contents/_CodeSignature/CodeResources` —— 正好是
- 这个形状,谁先被目录遍历撞上由目录顺序决定。于是两个 runner 跑的都是签名清单。
- frame-bench 说「宿主没打印 bench 行」,`verify-aot-native` 说「没装模块、没派发到任何
- 编译系统、一帧都没画」—— 三句话对一个文本文件全是真的。签名自桌面装配器落地起就在
- darwin 上无条件执行,也就是说这三条准则**从没在它们被写出来的平台上答过一次**。
-
-2. **Metal 上被测的那一帧是显示器的,不是引擎的。** `setPresentUncapped` 挑 Mailbox,
- 而 Dawn 的 Metal 后端只对 Immediate 清掉 `displaySyncEnabled`(`SwapChainMTL.mm`)——
- 请求成功了,什么也没改变。**没有任何东西会说出来**,因为被节流的一帧读起来就是
- 「花了一个刷新间隔」的一帧:200 个实体和 2,000 个、一个 draw 和零个 draw,每个 span
- 都是 16.6 ms,而 AOT 那两个 build 读出 1.00x —— 门禁把它报成「编译系统退回解释器」。
- **判定它的是进程自己的两个钟**:6.25 s 墙钟对 0.69 s CPU,也就是说这一帧 89% 的时间在等。
- 改成 Immediate 优先后同一帧读 3.03 ms,AOT 比值 9.3x。
-
-3. **然后第三堵:一帧可以整段花在*等*上,而报告里没有任何东西能说出来。** 造完天花板去
- 验它,读到 **1.00x —— 一个会通过的假绿**:两半都被压到 16.6 ms,比的是两帧显示器。
- 所以宿主现在发 `busy`(span 里真烧掉的 CPU 除以它的墙钟,取自线程自己的钟),低于一半
- 就**拒绝**而不是报数;被节流的跑读 8–11%。**每次比较里最便宜的那一帧先跳出来**,这个
- 方向是对的:它正是节流能压住、而另一半还在干活的那个。
-
- 两个已实测的成因:窗口被盖(benched 窗口现在主动要 `SDL_WINDOW_ALWAYS_ON_TOP`),以及
- **虚拟显示器**——远程桌面会话按自己的节拍发 drawable,帧再快也没用,置顶标志救不了。
- **这台机器现在就是第二种**(1920×1080 虚拟屏,`IODisplayWrangler` 不应答),所以
- `frame-bench --gate` 在这里会拒绝作答。天花板本身的标定是在没被节流的时候取的
- (drawing 10.3–10.6 / holding 2.45–2.89,破坏 17.0–17.2 / 2.46),数是干净的。
-
-**`thin` 那条准则的反复无常已查清,而我第一次归错了因。** 同一棵树上 compiled 侧读到过
-0.735 / 1.195 / 2.864 / 16.6 ms,我当时判成「`REPS=1`,采样不够」——**不是抖动,是同一个
-节流**:`busy` 上线后那个 2.87 ms 显示只有 25% 是 CPU。两对现在按同一套量(交错 + 至少
-3 reps 取最小,`PAIR_REPS` 一处),而**真正的修复是「测不成就别下判决」**:任何一半被
-`busy` 拒绝,那一对的计时判决就不再打印 —— 此前它会同时喊「a system is reaching the
-interpreter」,那是对引擎的诬告。校验和、「有没有真派发」、`walked`、「这一对是不是一对」
-都是计数,照常判。
-
-
-## 4. 重读 `rendering` 的判决,顺手解锁 fog / DOF / SSAO
-
-**〔2026-08-27 第二轮:先立标准,再用它。〕** 「什么阶段才可以改」此前没有答案,于是
-升级是一次做完、用散文论证、再也不复问的判断。两行的 `why` 只写着「还没被拿来定级」——
-那是给自己的备忘,不是判据。
-
-**新门禁 `check-tier-bar`:门槛就是 `check-freeze-bar` 对 `@public` 符号那三条,
-问到子系统 `entry` 头上** —— documented / tested / (值类型还要) 被某个 golden 项目调用。
-**它是地板,不是升级触发器**:过了只是「允许」,证据够不够**广**到值得承诺,仍然是判断,
-留在 `why` 里。它消掉的是另一种情况:一个**本来就不可能挣到**的声明,只因为没人有办法问。
-
-**它是标定出来的,不是发明的:六个 `public` 全部达标。** 上一级 16 行里 10 行达标;
-不达标的 6 行是门槛之前发布的,各自带着还欠什么(`OWED`,逐条复核,欠账还上那天门禁会说)。
-
-**用它之后:`tilemap` 和 `particles` 已升 `beta`。** 各只差一件——它自己的组件没有写下来的
-契约;补上,连 `Data` 接口一起承诺(`check-data-tiers` 要求「你写进去的字段」同级)。
-广度那半靠论证:**tilemap 两个认证游戏、其中一个每次改动都跑**,比四个已在这一级的行证据
-还多;**particles 一个,与 `spine`、`scene` 当初发布时同级**。
-
-**`rendering` 仍留 experimental,而现在有证据说为什么**:门槛报出 `Light` 和
-`PostProcessStack` **没有任何 golden 项目调用**——这是真的广度缺口,不是感觉。它的 `why`
-(一个游戏由它下面那几层构成,那些先冻)照旧成立。`mesh`、`physics-3d` 同理,门槛缺口很大。
-`math` 三个函数一个 golden 项目都没调;`services` 的三个基本没有证据。
-
-**~~一个便宜且已标好的改动~~ 已落地 2026-08-27。** `FrameConstants` 现在带上它自己那个
-矩阵的**逆**(不是 near/far —— 逆更通用:一个成员同时喂 fog、DOF、SSAO,而 near/far 只对
-透视成立)。注入头两侧都加了 `worldFromDepth(uv, depth)`,两边只差一行:GL 的 clip z 是
-[-1,1]、WebGPU 是 [0,1];xy 是共用的,因为两边画的是同一个屏幕三角形。
-
-**上传的是着色器看到的那个矩阵的逆**,不是引擎自己那份 —— 着色器反投影的是它自己的设备
-光栅化进去的那个 clip 空间。
-
-第一个消费者是 `distanceFog`,连着它的双后端像素门禁一起落地。门禁四个点里有两个在
-**同一面平墙**上、深度完全相同,而 90 度的眼睛离画面边缘比离中心远 1.41 倍 —— 一个读深度
-而不是读距离的实现会把这两点画成一样,容差够不到它们之间。双向 sabotage 验过:改成沿 z 量
-而不是沿射线量,两块方块照样过、那一个点变红。webgl2 / WebGPU / 软件光栅化器四个点逐字节一致。
-
-## 5. 两处小的,但正在削弱「清单是真的」〔已落地 2026-08-27〕
-
-- **`design-frame` 从来没绿过 —— 而且它根本没在量那个框。** 原因不是窗口大小:转过视角
- 之后设计画布跑出了视口,所以大多数行上只看得见它**一条**边框,量到的跨度是「那条边框
- 到视口边缘」——一个由窗口钉死的数,不是由框钉死的。所以它在一个尺寸下红、另一个尺寸下
- 「绿」:**绿的那次是假阳性**。修法是转完视角之后重新取景。
- 顺带挖出一个真的编辑器 bug:`frameCanvas` 按设计矩形自身的半宽高取景,而它旁边的
- `frameSelection` 按「**眼睛看到的**那个盒子」取景 —— 于是在任何转过的视角下按取景按钮
- 都会把画布框丢在视口外。正对时两者一样,所以一直没人发现。
- 还顺带补了一个命令:`view.frameCanvas`(视口一直有这个按钮,却没有命令,命令面板、
- 快捷键和 driver 都够不着它)。42/42 editor checks 绿。
-- **`RELEASE` 改成从 package.json 推导**。它曾是字面量,于是 0.58 是在一份标题写着
- 「0.57 exit criteria」的清单下发的。一个存在理由就是「不让清单和检查漂移」的文件,
- 不能自己成为版本号的第二处来源。
-
-## 6. `sprite-seam` 这一对在 webgpu 上是空转的〔已查清 2026-08-27〕
-
-**起因**:`--backend webgpu` 是 108/109,唯一的红是 `sprite-seam-off`(ratio 1.683,要求
-≥2.5),每次同一个数。把引擎改动 stash 掉重建后**同一个数**,所以不是新引入的。
-
-**这一对是干什么的**:`sprite-seam` 断言「上了 pixel-exact 的 render policy 之后没有缝」,
-`sprite-seam-off` 是它的**反向对照** —— 不上 policy 时缝**必须还在**,否则正向那条证明不了
-任何东西。度量是 `max(边界列台阶) / median(内部列台阶)`。
-
-**量到的**。两个后端的帧**只差一个像素**:第三道缝上,x=201,GL 给 `[81,65,206]`,而它两边
-是 `[59,47,219]` 和 `[41,32,230]` —— 一根往回跳的亮线,就是缝;WebGPU 给 `[44,35,228]`,
-顺着斜坡,没有缝。内部台阶两边都是 ~31,最差边界列 GL 是 94.1、WebGPU 是 51.5。
-
-**结论:这一对在 WebGPU 上不成立,而且正向那条是空转的。** WebGPU 上带 policy 是 1.357、
-不带是 1.683,**都在 limit 2 以下** —— 也就是说把被测的修复拿掉,正向门禁照样绿。一个不可能
-红的准则不是准则。所以两条都改成只跑 WebGL2,注释里带着这些数。
-
-**已经缩到很窄了〔同日续查〕。** 两帧一共差 **800 个像素**,全部落在 **4 列**上 ——
-54、127、128、201,每列 74 行,正好就是三道共享边。**不是全局半像素偏移**(那样精灵的
-外边也会差;顺带一提这个 fixture 的外边在屏幕外,所以「只有内边差」不能单独当证据,
-是「非边缘像素逐字节相同」才排除了它)。
-
-在 x=201(边界落在 201.14)上逐行相关:**WebGPU 那一列跟着 slice3 的第 0 个纹素走** ——
-也就是像素中心 201.5 所在的那个精灵,按像素中心规则这是**对的**;而 **WebGL2 给出的值
-在两侧邻居的区间之外**(`[81,65,206]` vs `[59,47,219]` / `[41,32,230]`),所以它既不是
-左边那块也不是右边那块的采样,是第三个值。
-
-**这推翻了一条被当成物理定律的东西。** [[2d-seams-three-mechanisms]] 的机制 C 说
-「纹素→像素比不是整数就必然有缝」。WebGPU 在**同一个比值**下给出的是一条单调的斜坡,
-没有缝。所以机制 C 是 **WebGL2 的行为**,不是定律。
-
-**下一步卡在 fixture 上**:四张切片是同一条渐变的四段,数值互相混叠(逐行相关把 GL 那
-一列判给「slice0 col35」,误差 12.3,和正确答案的 11.6 分不开)。要继续查,先要一个
-**四片可区分**的 fixture(比如四个纯色),再回到 GL 那条路上看是谁写了那一列。
-
-**顺带记一条**:本地 `pnpm verify` 不跑像素门禁,而像素门禁的 webgpu 那一半只有本机有真
-适配器才跑得动(CI runner 没有)。所以这类红能躺很久 ——
-和 [[gates-cannot-see-what-they-do-not-sample]] 同一类。
-
-## 明确不做的(省得重新评估)
-
-- **shadow pass 变成声明的 pass。** 它本来要买的东西(可采样 depth、atlas 的生命周期)
- 已经到手了 —— 前者根本不需要它,后者靠 `rg::TargetPool` 的 per-frame 出借拿到。剩下的
- 是一个声明点加一个 graph 拥有的 atlas,而代价是第二条 draw list + 第二个 transient pool。
- **没有新理由就别开。**
-- **本端预测 + 和解、relevancy / 兴趣管理、带宽量化。** RC11 的余项,说好需求驱动。
-- **`ai` / `networking` 的定级。** 刻意排在后面:0.50 冻的是「一个游戏由什么构成」,
- 建立在其上的层要等下面这些定下来。
-
-## 建议的顺序
-
-**1 → 5 → 4 → 3 → 2。** 〔1、3、5、6 已关闭;4 的工程那半已落地,定级待拍板;剩 2,卡在 NDK。〕
-
-先把量到的浪费修掉(1),顺手清掉两处假的清单项(5),再做一次定级重读 + FrameConstants
-(4,这两个是「读」和「一个成员」,不是工程),然后是时间门禁(3),最后开 Android(2,
-那是以周计的)。
diff --git a/pipeline/src/assets/fbxImport.ts b/pipeline/src/assets/fbxImport.ts
index c818cc1c3..9638dcaff 100644
--- a/pipeline/src/assets/fbxImport.ts
+++ b/pipeline/src/assets/fbxImport.ts
@@ -403,12 +403,9 @@ function buildNodes(scene: FbxScene, meshIndexOf: Map<string, number[]>): Import
const INVISIBLE_COLOR_SHARE = 0.95;
/**
- * The vertex colours to actually use: `colors`, or null when the layer would
- * make the mesh invisible (see the call site). Warns, naming the share, so the
- * substitution is never silent.
- *
- * Exported for the test: the decision is a threshold on real numbers, and the
- * FBX fixtures write no colour layer to drive it end to end.
+ * The vertex colours to use: `colors`, or null when the layer would make the
+ * mesh invisible — null takes the same white path a mesh with no colour layer
+ * takes. Warns with the share, so the substitution is never silent.
*/
export function dropInvisibleColors(colors: Float32Array, vertexCount: number,
name: string, warnings: string[]): Float32Array | null {
@@ -433,15 +430,9 @@ function buildMesh(part: FbxMeshPart, name: string, payload: Uint8Array,
const weights = part.weights ? floats(payload, part.weights) : null;
const indices = uints(payload, part.indices);
const vertexCount = part.vertexCount;
- // MeshRenderer multiplies its tint INTO the vertex colours, so a layer that
- // is transparent nearly everywhere is a mesh that imports, occludes, and
- // draws nothing — with no error anywhere to say why. Nobody authors that;
- // it is what a colour layer whose indices did not match the mesh decays to
- // (ufbx clamps the bad index and hands back zeroes, warning only "Clamped
- // index"). Measured on a real project: 3 of 80 building models arrived 96-99%
- // alpha-zero and imported invisible. Drop the layer to white and SAY so —
- // white is what a mesh with no colour layer already gets, so the fallback is
- // the ordinary path rather than a special case.
+ // MeshRenderer multiplies its tint INTO these, so an all-transparent layer
+ // draws nothing. That is what a colour layer whose indices missed the mesh
+ // decays to, once ufbx clamps the bad index and returns zeroes.
const colors = part.colors ? dropInvisibleColors(floats(payload, part.colors),
part.vertexCount, name, warnings) : null;
// A pose the renderer cannot hold is not a pose — see the same read in the
diff --git a/pipeline/tests/fbx-import.test.ts b/pipeline/tests/fbx-import.test.ts
index ff8c836bd..db6e186fc 100644
--- a/pipeline/tests/fbx-import.test.ts
+++ b/pipeline/tests/fbx-import.test.ts
@@ -230,11 +230,8 @@ describe('fbx reporting', () => {
});
/**
- * A colour layer whose indices did not match the mesh decays to zeroes (ufbx
- * clamps the bad index and says only "Clamped index"), and MeshRenderer
- * multiplies its tint INTO those — so the model imports, occludes, and draws
- * nothing. Real project, real numbers: 3 of 80 building models arrived 96-99%
- * alpha-zero and were invisible with no error anywhere.
+ * MeshRenderer multiplies its tint into the vertex colours, so an
+ * all-transparent layer draws nothing. Measured: 3 of 80 real models.
*/
describe('fbx vertex colours that would import an invisible mesh', () => {
/** `count` vertices, of which the first `opaque` have alpha 1. */
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index e8cecd452..9d28891f8 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -218,7 +218,7 @@ export const SCENES = [
// needs. The PAIR is the gate: `-off` asserts the measurement still finds one.
// WebGL2 only, and measured: on WebGPU these frames differ at ONE pixel of one
// boundary, so the ratio is 1.68 without the policy and 1.36 with it - both under
- // the limit, which leaves the pair proving nothing there. See docs/ROADMAP.md.
+ // the limit, which leaves the pair proving nothing there.
{ id: "sprite-seam", tier: "pr", env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-seam.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-seam.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_RENDER_RESOLUTION: "1", ESTELLA_VERIFY_SEAM: "{\"period\":73.143,\"phase\":54.857,\"band\":{\"y0\":100,\"y1\":156},\"limit\":2}" } },
{ id: "sprite-seam-off", tier: "pr", env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-seam.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-seam.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_SEAM: "{\"period\":73.143,\"phase\":54.857,\"band\":{\"y0\":100,\"y1\":156},\"atLeast\":2.5}" } },
{ id: "ysort-on", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_YSORT: "1", ESTELLA_VERIFY_SCENE: "/scenes/ysort.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ysort.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.5,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.5,\"y\":0.75,\"rgb\":[0,255,0],\"tol\":30}]" } },