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
test(render): the seam gate, and the pair that makes it mean something
yhhd88e03c5a2f0
diff --git a/fixtures/scenes/sprite-seam.esscene b/fixtures/scenes/sprite-seam.esscenenew file mode 100644index 000000000..16c9b697c--- /dev/null+++ b/fixtures/scenes/sprite-seam.esscene@@ -0,0 +1,174 @@+{+ "version": 4,+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 112,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Slice0",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -96,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 64,+ "y": 64+ },+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "texture": "@uuid:aaaaaaaa-5ea0-4000-8000-000000000000"+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Slice1",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -32,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 64,+ "y": 64+ },+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "texture": "@uuid:aaaaaaaa-5ea0-4000-8000-000000000001"+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "Slice2",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 32,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 64,+ "y": 64+ },+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "texture": "@uuid:aaaaaaaa-5ea0-4000-8000-000000000002"+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "Slice3",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 96,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 64,+ "y": 64+ },+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "texture": "@uuid:aaaaaaaa-5ea0-4000-8000-000000000003"+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/sprite-seam.textures.json b/fixtures/scenes/sprite-seam.textures.jsonnew file mode 100644index 000000000..f51420dd1--- /dev/null+++ b/fixtures/scenes/sprite-seam.textures.json@@ -0,0 +1,6 @@+{+ "aaaaaaaa-5ea0-4000-8000-000000000000": "/scenes/sprite-seam/slice0.png",+ "aaaaaaaa-5ea0-4000-8000-000000000001": "/scenes/sprite-seam/slice1.png",+ "aaaaaaaa-5ea0-4000-8000-000000000002": "/scenes/sprite-seam/slice2.png",+ "aaaaaaaa-5ea0-4000-8000-000000000003": "/scenes/sprite-seam/slice3.png"+}diff --git a/fixtures/scenes/sprite-seam/slice0.png b/fixtures/scenes/sprite-seam/slice0.pngnew file mode 100644index 000000000..7de29a4f6Binary files /dev/null and b/fixtures/scenes/sprite-seam/slice0.png differdiff --git a/fixtures/scenes/sprite-seam/slice1.png b/fixtures/scenes/sprite-seam/slice1.pngnew file mode 100644index 000000000..74ebc376cBinary files /dev/null and b/fixtures/scenes/sprite-seam/slice1.png differdiff --git a/fixtures/scenes/sprite-seam/slice2.png b/fixtures/scenes/sprite-seam/slice2.pngnew file mode 100644index 000000000..c9306d957Binary files /dev/null and b/fixtures/scenes/sprite-seam/slice2.png differdiff --git a/fixtures/scenes/sprite-seam/slice3.png b/fixtures/scenes/sprite-seam/slice3.pngnew file mode 100644index 000000000..6a9ab208eBinary files /dev/null and b/fixtures/scenes/sprite-seam/slice3.png differdiff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjsindex 62155a13a..a631dda41 100644--- a/tools/check-render-scenes.mjs+++ b/tools/check-render-scenes.mjs@@ -44,7 +44,10 @@ for (const s of SCENES) {// the sharper kind: what a frame cost is the half no pixel can show — as an// exact value where a scene is small enough to enumerate, and as a CEILING// where it is not.- const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW+ // A SEAM is an expectation too, and the kind a point probe cannot state: a+ // column that behaves unlike its neighbours on a grid is not a pixel colour.+ const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_SEAM+ || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW|| s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS|| s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX|| s.env.ESTELLA_VERIFY_DRAW_CALLSdiff --git a/tools/lib/seamProbe.mjs b/tools/lib/seamProbe.mjsindex 612149604..2701b58e1 100644--- a/tools/lib/seamProbe.mjs+++ b/tools/lib/seamProbe.mjs@@ -88,10 +88,20 @@ export function seamRatio(px, w, h, band, period, phase, slack = 1) {}/**- * Verdict for a gate: the ratio, and whether it clears `limit`.- * Kept separate from {@link seamRatio} so a failure can report the number.+ * Verdict for a gate: the ratio, and whether it sits where it was told to.+ *+ * `atLeast` is the other direction, and a pair needs it: a scene asserting the+ * seam is GONE proves nothing on its own until its twin asserts the same+ * measurement still finds one with the fix off.*/-export function checkSeam(px, w, h, { band, period, phase = 0, slack = 1, limit = 2 }) {+export function checkSeam(px, w, h, { band, period, phase = 0, slack = 1, limit, atLeast }) {const ratio = seamRatio(px, w, h, band, period, phase, slack);- return { ratio, limit, ok: ratio <= limit };+ const cap = limit ?? (atLeast === undefined ? 2 : Infinity);+ const floor = atLeast ?? 0;+ // Only the bounds that were asked for appear: a JSON `Infinity` serialises to+ // null, and a failing gate's report should not read like a bug of its own.+ const out = { ratio, ok: ratio <= cap && ratio >= floor };+ if (Number.isFinite(cap)) out.limit = cap;+ if (floor > 0) out.atLeast = floor;+ return out;}diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex 286eafe22..e7c6bf1a8 100644--- a/tools/render-host/run.mjs+++ b/tools/render-host/run.mjs@@ -40,6 +40,7 @@ import path from 'node:path';import { fileURLToPath } from 'node:url';import { onRendererConsole } from '../lib/rendererConsole.mjs';import { serveHost } from '../lib/staticServer.mjs';+import { checkSeam } from '../lib/seamProbe.mjs';// SwiftShader rasterizes on the CPU; run the whole electron tree below normal// priority (child processes inherit the class) so a verify never starves the@@ -162,7 +163,7 @@ function finish(result, server) {// which no pixel in the frame can show.const pickOk = !result.pick || result.pick.hit === result.pick.want;const renderedOk = result.capture?.rendered ?? false;- const ok = result.ok && renderedOk && (result.expect?.ok ?? true) &&+ const ok = result.ok && renderedOk && (result.expect?.ok ?? true) && (result.seam?.ok ?? true) &&(result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&(result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) &&(result.draws?.ok ?? true) && (result.counters?.ok ?? true) &&@@ -581,6 +582,30 @@ app.whenReady().then(async () => {return { points: out, ok: out.every((o) => o.ok) };`);}+ // ESTELLA_VERIFY_SEAM is JSON { period, phase, band:{y0,y1}, limit?, atLeast? }+ // in TOP-DOWN screen pixels. The pixels come back to node so seamProbe stays+ // one implementation rather than being re-typed into an injected script.+ let seam = null;+ if (process.env.ESTELLA_VERIFY_SEAM) {+ const spec = JSON.parse(process.env.ESTELLA_VERIFY_SEAM);+ const frame = await readFrame(`+ let s = '';+ const CH = 0x8000;+ for (let i = 0; i < px.length; i += CH) {+ s += String.fromCharCode.apply(null, px.subarray(i, Math.min(i + CH, px.length)));+ }+ return { b64: btoa(s), w, h };+ `);+ const raw = Buffer.from(frame.b64, 'base64');+ // Readback rows are bottom-up; the band is stated the way a viewer reads a+ // frame, so the rows are flipped rather than the caller doing the arithmetic.+ const rows = Buffer.alloc(raw.length);+ const stride = frame.w * 4;+ for (let y = 0; y < frame.h; y++) {+ raw.copy(rows, y * stride, (frame.h - 1 - y) * stride, (frame.h - y) * stride);+ }+ seam = checkSeam(rows, frame.w, frame.h, spec);+ }// Optional PNG dump (ESTELLA_VERIFY_OUT) of the engine framebuffer (not the// page) so the rendered frame can be eyeballed. GL readback is bottom-up → flip.if (process.env.ESTELLA_VERIFY_OUT) {@@ -716,7 +741,7 @@ app.whenReady().then(async () => {};`);}- finish({ ok: true, entityCount, drawCalls, draws, counters, profile, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick, cameraTarget }, server);+ finish({ ok: true, entityCount, drawCalls, draws, counters, profile, capture, expect, seam, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick, cameraTarget }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 6a7d1f68e..825d2d68b 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -213,6 +213,11 @@ export const SCENES = [// Where the UI layout box SITS. The camera is driven away from the origin at runtime, so the box moves without resizing: the unparented Canvas (a screen root) must travel with it — red/green stay in their quadrants — while the Canvas parented to a world entity must not, landing blue at the anchor's own world position. Before screen roots existed the whole HUD stayed at the origin and this frame came back black.{ id: "ui-screen-root", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/ui-screen-root.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-screen-root.textures.json", ESTELLA_VERIFY_W: "640", ESTELLA_VERIFY_H: "360", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_MOVE: "{\"component\":\"Camera\",\"to\":[5000,-800],\"steps\":4}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.75,\"y\":0.75,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.75,\"y\":0.25,\"rgb\":[0,0,255],\"tol\":30},{\"x\":0.25,\"y\":0.75,\"rgb\":[0,0,0],\"tol\":30}]" } },// Y-sort: same scene twice — mask on flips the overlap to the lower (higher-Y-key) entity; mask off preserves submission order. Both asserted so neither path can silently regress.+ // 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}" } },{ 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.diff --git a/tools/tests/seam-probe.test.ts b/tools/tests/seam-probe.test.tsindex 5c850bb87..598b3d8b3 100644--- a/tools/tests/seam-probe.test.ts+++ b/tools/tests/seam-probe.test.ts@@ -84,6 +84,14 @@ describe('checkSeam', () => {const good = checkSeam(wall(0), W, H, { band: BAND, period: PERIOD, limit: 2 });expect(good.ok).toBe(true);});++ it('asserts a FLOOR too, which is what a paired gate needs', () => {+ // The twin of "the seam is gone" is "the same measurement still finds one+ // with the fix off". Without a floor that half cannot be written, and the+ // first half proves nothing on its own.+ expect(checkSeam(wall(40), W, H, { band: BAND, period: PERIOD, atLeast: 2.5 }).ok).toBe(true);+ expect(checkSeam(wall(0), W, H, { band: BAND, period: PERIOD, atLeast: 2.5 }).ok).toBe(false);+ });});describe('columnSteps', () => {