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): a readback the engine refuses is not a blank frame

yhhc53798c541c0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 512f2e3be..97da73b35 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -214,6 +214,20 @@ published separately; it ships inside the editor.
### Fixed
+- **A readback the engine refuses is a failure, not a blank frame.** The pixel harness
+ asked the engine for its own pixels and, when that came back null, read the composited
+ PAGE instead. On the hidden window every verifier runs in, that page is blank — so a
+ readback the engine declined produced a frame that had rendered nothing, and every
+ probe in the scene agreed with it. It now says so, by name, and only falls back where
+ the build cannot answer at all.
+
+ Which is how this was found: on the second backend a scene that renders a shadow map
+ refuses its own readback once it has stepped past about 24 frames. `point-shadow` at
+ `ESTELLA_VERIFY_STEPS=32` reproduces it and at 24 does not; a scene with no shadow map
+ is fine at 200. What it is not is a rendering fault — the next readback in the same run
+ returns the right pixels. Nothing in the corpus steps that far, so no gate moved, and
+ the defect behind it is still open.
+
- **A shadow map stores the depth at the fragment, not an interpolation of its
corners'.** The depth written into a map was `z / w`, computed in the vertex stage and
carried across the triangle as a varying. `z / w` is not affine across a triangle, so
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index b566d3497..eb5007eaf 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -461,10 +461,17 @@ app.whenReady().then(async () => {
// Both backends are read the same way: the ENGINE's pixels, in the page.
// Reading the composited page instead answers what a display would show —
// rgb(0,255,0) comes back as rgb(58,254,32).
+ // A build that CAN answer and does not is a failure, not a reason to read the
+ // page: on a hidden window that page is blank, so falling back turns a refused
+ // readback into a frame that rendered nothing, which every probe then agrees with.
const readFrame = (expr) => exec(`(async () => {
const api = window.__estellaHeadless.api;
- const c = (api.captureViewportPixels ? await api.captureViewportPixels() : null)
- ?? api.captureViewport();
+ let c = null;
+ if (api.captureViewportPixels) {
+ c = await api.captureViewportPixels();
+ if (!c) throw new Error('captureViewportPixels: the engine refused its own readback');
+ }
+ c = c ?? api.captureViewport();
const px = c.rgba, w = c.width, h = c.height;
${expr}
})()`);