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 frame debugger's reasons and replay are held on both backends
esengine0fe0c8f54a84
diff --git a/desktop b/desktopindex 771a8d564..e345319ce 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 771a8d564ff7fbfa4a036a0fe3ba6a120537595d+Subproject commit e345319ce5830ebb922e1d80a57a49fed65cf26adiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.mjsindex 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.tsindex 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.mjsindex 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.mjsindex 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