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.

test(render): the frame debugger's reasons and replay are held on both backends

esengine0fe0c8f54a84
diff --git a/desktop b/desktop
index 771a8d564..e345319ce 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 771a8d564ff7fbfa4a036a0fe3ba6a120537595d
+Subproject commit e345319ce5830ebb922e1d80a57a49fed65cf26a
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 9ea18e4bf..19f3f68d9 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 103,
- "experimental": 2095,
+ "experimental": 2100,
"deprecated": 3
},
- "total": 2313,
+ "total": 2318,
"subsystems": [
{
"id": "ecs",
diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjs
index cd2a00c50..e0b5f0025 100644
--- a/tools/check-render-scenes.mjs
+++ b/tools/check-render-scenes.mjs
@@ -46,7 +46,7 @@ for (const s of SCENES) {
|| 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_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG
|| s.env.ESTELLA_VERIFY_DRAW_CALLS
|| s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
if (!asserts && !s.rendersOnly) {
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index b221cbeb8..059859ef8 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -20,7 +20,7 @@ import {
createWebApp, setEditorMode, setPlayMode, Assets, acquireWebGPUDevice,
loadSceneData, Renderer, instantiatePrefab, writeFieldPath, Transform, Name,
getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,
- getContextLossGuardInfo, decodeImagePixels, captureFramePixels,
+ getContextLossGuardInfo, decodeImagePixels, captureFramePixels, captureFrame, replayDraw, BatchBreak,
RenderTexture, Camera, Sprite,
EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,
ProfileRecorder, AnimatorController, Timeline, onDeviceRestored, Schedule, defineSystem,
@@ -426,6 +426,40 @@ const api = {
};
},
+ /**
+ * The frame debugger's own claims, on this backend: a capture's reasons, and
+ * how many pixels a replay through the first and through the last draw of a
+ * pass paint. Painted is counted by alpha, which the replay clears to zero.
+ */
+ async frameDebug(): Promise<{
+ draws: number; passes: number; breaks: Record<string, number>;
+ first: number; last: number; differ: number; matches: boolean;
+ } | null> {
+ if (!module) return null;
+ const next = async () => { await api.step(1, 1 / 60); };
+ const cap = await captureFrame(module, next);
+ if (!cap) return null;
+ const breaks: Record<string, number> = {};
+ for (const d of cap.drawCalls) {
+ const name = BatchBreak[d.breakReason];
+ breaks[name] = (breaks[name] ?? 0) + 1;
+ }
+ const pass = cap.drawCalls.filter((d) => d.pass === cap.drawCalls[0].pass);
+ const a = await replayDraw(module, pass[0].index, next);
+ const b = await replayDraw(module, pass[pass.length - 1].index, next);
+ if (!a || !b) return null;
+ const painted = (px: Uint8ClampedArray) => { let n = 0; for (let i = 3; i < px.length; i += 4) if (px[i] > 0) n++; return n; };
+ let differ = 0;
+ for (let i = 0; i < a.image.data.length; i += 4) {
+ if (Math.abs(a.image.data[i] - b.image.data[i]) + Math.abs(a.image.data[i + 3] - b.image.data[i + 3]) > 16) differ++;
+ }
+ return {
+ draws: cap.drawCalls.length, passes: cap.passCount, breaks,
+ first: painted(a.image.data), last: painted(b.image.data), differ,
+ matches: a.matchesCapture && b.matchesCapture,
+ };
+ },
+
/** Engages the engine's per-frame scopes and counters. Off by default, and
* asked for only by a gate that measures what a frame COST — the scopes are
* timed work the frames a pixel assertion looks at should not carry. */
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index bf93eed27..9cb51b124 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -32,6 +32,7 @@
* ESTELLA_VERIFY_ORBIT turn the editor eye before capture ("yaw,pitch" degrees)
* ESTELLA_VERIFY_COUNTERS engine counters the drawn frame must report (JSON)
* ESTELLA_VERIFY_COUNTERS_MAX counters the frame must stay UNDER — a budget (JSON)
+ * ESTELLA_VERIFY_FRAME_DEBUG capture the frame and replay it (the frame debugger)
* ESTELLA_VERIFY_SCALE copy the scene's content onto a grid (JSON), for a cost gate
* ESTELLA_VERIFY_OUTPUT_TRANSFORM the frame's output curve ("aces")
* ESTELLA_VERIFY_PROFILE record N further frames and report the TS/C++ cost split
@@ -209,7 +210,7 @@ function finish(result, server) {
(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) &&
+ (result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.frameDebug?.ok ?? true) &&
(result.roundtrip?.ok ?? true) && deviceLossOk && meshOk && pickOk;
const why = assetsOk ? '' : `: could not load ${result.missingAssets.join(', ')}`;
console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})${why}`);
@@ -269,7 +270,7 @@ app.whenReady().then(async () => {
}
// The engine's per-frame counters are only recorded while profiling is on, and
// it goes on BEFORE the steps: what is read afterwards is the last frame's.
- if (process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX) {
+ if (process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || process.env.ESTELLA_VERIFY_FRAME_DEBUG) {
await exec('window.__estellaHeadless.api.setCpuProfiling(true)');
}
// Project render config stand-in: ESTELLA_VERIFY_YSORT = layer bitmask
@@ -702,6 +703,23 @@ app.whenReady().then(async () => {
];
counters = { points, ok: points.every((p) => p.ok) };
}
+ // The frame debugger on this backend: its reasons are the merge's own counters
+ // for the frame, and a replay through the last draw of a pass shows more than
+ // one through the first.
+ let frameDebug = null;
+ if (process.env.ESTELLA_VERIFY_FRAME_DEBUG) {
+ const got = await exec('window.__estellaHeadless.api.frameDebug()');
+ const raw = await exec('window.__estellaHeadless.api.getCounters()');
+ const lower = (entries) => Object.fromEntries(entries.map(([k, v]) => [k.toLowerCase(), v]).sort());
+ const counted = lower(Object.entries(raw ?? {}).filter(([k]) => k.startsWith('batch.break.'))
+ .map(([k, v]) => [k.slice('batch.break.'.length), v]));
+ const reported = lower(Object.entries(got?.breaks ?? {}).filter(([k]) => k !== 'None'));
+ const sameReasons = JSON.stringify(counted) === JSON.stringify(reported);
+ frameDebug = {
+ ...got, counted, sameReasons,
+ ok: Boolean(got) && got.draws > 0 && got.matches && sameReasons && got.last > 0 && got.differ > 0,
+ };
+ }
// Optional color/orientation assertion: ESTELLA_VERIFY_EXPECT is a JSON array of
// { x, y, rgb:[r,g,b], tol? } where x,y are normalized [0,1] from the TOP-LEFT.
// This is the guard the all-textures-upside-down upload bug would have tripped
@@ -920,7 +938,7 @@ app.whenReady().then(async () => {
`);
if (respaced != null) grid = { ...grid, respacedPixels: respaced, ok: grid.ok && respaced > 300 };
}
- finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, profile, capture, expect, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
+ finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, profile, capture, expect, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index af48db222..c756cc9c6 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -75,6 +75,8 @@ export const SCENES = [
// horizon is. A plane turned to meet the eye lights the frame evenly and passes
// the coverage check, so "grazing" is what tells the two apart.
{ id: "editor-grid-grazing", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_GRID_EXPECT: "grazing", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,4", ESTELLA_VERIFY_STEPS: "3" } },
+ { id: "frame-debugger-2d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-rendering.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-rendering.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },
+ { id: "frame-debugger-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ssao.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },
{ id: "mesh-renderer", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-renderer.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-renderer.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40}]" } },
// One mask, both its sides, and a sprite that never asked. A mask that does nothing
// paints the frame red; a side that inverted swaps green and red. The blue bar states