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.

fix(gates): the sprite-seam pair proved nothing on WebGPU

yhh826bbbcc0776
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea703db91..3765cb54e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,26 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **The sprite-seam pair proved nothing on WebGPU, and one half of it said so.**
+ `sprite-seam` asserts the pixel-exact render policy removes a seam;
+ `sprite-seam-off` is its negative control, and it was red on WebGPU — the same
+ ratio every run, and the same one with the release's engine changes stashed.
+
+ The two backends' frames are identical except at ONE pixel. On the third
+ boundary, WebGL2 draws `[81,65,206]` between neighbours of `[59,47,219]` and
+ `[41,32,230]` — a line stepping back up, which is the seam — where WebGPU
+ draws `[44,35,228]`, on the ramp. Interior step is ~31 on both; the worst
+ boundary is 94.1 against 51.5.
+
+ So there is no seam on WebGPU to control for — and the POSITIVE gate is
+ vacuous there too: 1.357 with the policy and 1.683 without, both under its
+ limit of 2, so it passes whether or not the thing it tests is applied. The
+ pair runs on WebGL2 only now, carrying those numbers, and what makes the
+ backends differ is written down rather than guessed at (it is not the address
+ mode: both default to ClampToEdge and GL applies it).
+
### Added
- **A sampled depth can be put back in the world.** `FrameConstants` carries the
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 905d19134..768a03001 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -162,18 +162,31 @@ experimental 对创作者读起来是「大半个引擎没做完」,哪怕其
「0.57 exit criteria」的清单下发的。一个存在理由就是「不让清单和检查漂移」的文件,
不能自己成为版本号的第二处来源。
-## 6. 一个既有的红:`sprite-seam-off` 在 webgpu 上
+## 6. `sprite-seam` 这一对在 webgpu 上是空转的〔已查清 2026-08-27〕
-2026-08-27 发现。`node tools/verify-render.mjs --backend webgpu` 是 108/109,唯一的红是
-`sprite-seam-off`:seam ratio **1.6832844574779984**,要求 ≥ 2.5,而且**每次都是同一个数**
-(不是抖动)。把引擎改动 stash 掉重建后是**同一个数**,所以它不是这次改出来的。
+**起因**:`--backend webgpu` 是 108/109,唯一的红是 `sprite-seam-off`(ratio 1.683,要求
+≥2.5),每次同一个数。把引擎改动 stash 掉重建后**同一个数**,所以不是新引入的。
-**为什么它一直没人管**:本地 `pnpm verify` 不跑像素门禁,而像素门禁的 webgpu 那一半只有
-本机有真适配器时才跑得动(CI runner 没有)。所以这是一个「没有任何东西在采样它」的洞 ——
-和 [[gates-cannot-see-what-they-do-not-sample]] 同一类。webgl2 那边 111/111 全绿。
+**这一对是干什么的**:`sprite-seam` 断言「上了 pixel-exact 的 render policy 之后没有缝」,
+`sprite-seam-off` 是它的**反向对照** —— 不上 policy 时缝**必须还在**,否则正向那条证明不了
+任何东西。度量是 `max(边界列台阶) / median(内部列台阶)`。
-查它的起点是 `2d-seams-three-mechanisms` 那条记录:内部误差 vs 边界误差能区分三种机制,
-而 `pixelPerfect` 只贴位置、不贴缩放。
+**量到的**。两个后端的帧**只差一个像素**:第三道缝上,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,注释里带着这些数。
+
+**还没答的**:WebGPU 为什么不出这个 artifact?**不是寻址模式** —— 两边默认都是
+`TextureWrap::ClampToEdge`(`GfxEnums.hpp`),GL 也确实设了(`GLDevice.cpp:1079`)。最像的
+解释是两块相邻 quad 共享边上「哪一块盖住那个像素」的光栅化裁定不同。要往下查就从
+`2d-seams-three-mechanisms` 那条记录的机制 C 开始:纹素→像素比不是整数。
+
+**顺带记一条**:本地 `pnpm verify` 不跑像素门禁,而像素门禁的 webgpu 那一半只有本机有真
+适配器才跑得动(CI runner 没有)。所以这类红能躺很久 ——
+和 [[gates-cannot-see-what-they-do-not-sample]] 同一类。
## 明确不做的(省得重新评估)
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 3d88da5c7..e8cecd452 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -216,8 +216,11 @@ export const SCENES = [
// Slices of one continuous pattern, each its OWN texture, at a fractional
// world-units-per-pixel — seamless art and a non-integer ratio are what a seam
// needs. The PAIR is the gate: `-off` asserts the measurement still finds one.
- { id: "sprite-seam", tier: "pr", webgpu: true, 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", webgpu: true, 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}" } },
+ // 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.
+ { 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}]" } },
{ id: "ysort-off", tier: "pr", webgpu: true, env: { 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\":[255,0,0],\"tol\":30}]" } },
// Depth layers (2.5D): same scene twice, one project setting apart. The near sprite is in the LOWER layer and both merge into ONE draw call, so inside the batch the order is fixed by index — no amount of sorting can produce the depth answer, which is what makes the pair discriminating.