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
tools(render): what the cost harness and the render host could not see - the terrain-water cost harness played every variant after the first in the browser the first had used, about 6 ms a frame dearer at 1080p (the same scene written back unchanged read 18.6 ms first and 24.9 ms second), so whatever ran second looked expensive: each variant now has a browser of its own; its --shots were page screenshots, which show the start screen a stepped game keeps over its canvas, and are now the engine's own frame read back; it counts material bakes drawn while frames are timed. The render host takes ESTELLA_VERIFY_COUNTERS_MIN, a floor (that a thing happened at all), and ESTELLA_VERIFY_CONSOLE=all prints every line of the page's console
yhh5d80c4eff340
diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjsindex fc661c6c1..f7c5d204a 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_STUDIO || s.env.ESTELLA_VERIFY_SHADING || s.env.ESTELLA_VERIFY_LIGHTING_SPLIT || s.env.ESTELLA_VERIFY_SKIN_WEIGHTS || 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_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED || s.env.ESTELLA_VERIFY_TWINS+ || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_COUNTERS_MIN || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED || s.env.ESTELLA_VERIFY_TWINS|| s.env.ESTELLA_VERIFY_DRAW_CALLS || s.env.ESTELLA_VERIFY_NINE_SLICE|| s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';if (!asserts && !s.rendersOnly) {diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex eb65368de..b6b11a4c1 100644--- a/tools/render-host/run.mjs+++ b/tools/render-host/run.mjs@@ -36,6 +36,7 @@* ESTELLA_VERIFY_SKIN_WEIGHTS colour a skinned entity by joint weights (JSON {id, joints}; see the block)* 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_COUNTERS_MIN counters the frame must reach at least — that something happened at all (JSON)* ESTELLA_VERIFY_GPU_PASSES print|require — the GPU time of each render-graph pass on this backend (local; needs a timer)* ESTELLA_VERIFY_FRAME_DEBUG capture the frame and replay it (the frame debugger)* ESTELLA_VERIFY_UNIFORM the frame is one colour on purpose; ESTELLA_VERIFY_COUNT says which@@ -277,6 +278,8 @@ app.whenReady().then(async () => {if (GL_TRACE && msg.startsWith('GLTRACE ')) { appendFileSync(GL_TRACE, msg.slice(8) + '\n'); return; }// `webgpu` spelled out: "webgl" does not match it, so the second backend's// boot — including which adapter served it — was the one thing never shown.+ // ESTELLA_VERIFY_CONSOLE=all: every line, whole. A WebGPU validation message names the call and the texture and none of the words below.+ if (process.env.ESTELLA_VERIFY_CONSOLE === 'all') { console.log('[renderer]', msg); return; }if (/error|fail|unwind|exception|webgl|webgpu|adapter|recovery|placeholder/i.test(msg)) console.log('[renderer]', msg.slice(0, 240));});await win.loadURL(url);@@ -311,7 +314,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 || process.env.ESTELLA_VERIFY_FRAME_DEBUG || PREPASS) {+ if (process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || process.env.ESTELLA_VERIFY_COUNTERS_MIN || process.env.ESTELLA_VERIFY_FRAME_DEBUG || PREPASS) {await exec('window.__estellaHeadless.api.setCpuProfiling(true)');}// Project render config stand-in: ESTELLA_VERIFY_YSORT = layer bitmask@@ -734,11 +737,13 @@ app.whenReady().then(async () => {// value; a name the frame never set reports null, which fails rather than reading 0.// ESTELLA_VERIFY_COUNTERS_MAX is the same object read as a CEILING, a different claim:// exact pins a scene small enough to enumerate, a ceiling asks whether cost stayed- // bounded where nobody can. Both fail on a counter the frame never set.+ // bounded where nobody can. ESTELLA_VERIFY_COUNTERS_MIN is a FLOOR: that a thing happened+ // at all, where how often is the engine's business. All fail on a counter the frame never set.let counters = null;- if (process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || PREPASS) {+ if (process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || process.env.ESTELLA_VERIFY_COUNTERS_MIN || PREPASS) {const want = JSON.parse(process.env.ESTELLA_VERIFY_COUNTERS ?? '{}');const ceiling = JSON.parse(process.env.ESTELLA_VERIFY_COUNTERS_MAX ?? '{}');+ const floor = JSON.parse(process.env.ESTELLA_VERIFY_COUNTERS_MIN ?? '{}');const got = await exec('window.__estellaHeadless.api.getCounters()');const points = [...Object.entries(want).map(([name, value]) => ({@@ -748,6 +753,10 @@ app.whenReady().then(async () => {name, max: value, got: got?.[name] ?? null,ok: typeof got?.[name] === 'number' && got[name] <= value,})),+ ...Object.entries(floor).map(([name, value]) => ({+ name, min: value, got: got?.[name] ?? null,+ ok: typeof got?.[name] === 'number' && got[name] >= value,+ })),// A prepass twin of a scene that never had a prepass proves nothing about it: the draw it took part in is counted....(PREPASS ? [{ name: 'render.prepass.draws', min: 1, got: got?.['render.prepass.draws'] ?? null,ok: (got?.['render.prepass.draws'] ?? 0) >= 1 }] : []),@@ -777,7 +786,7 @@ app.whenReady().then(async () => {await exec('window.__estellaHeadless.api.setCpuProfiling(true)');const scoped = await settle('window.__estellaHeadless.api.getGpuScopes()', (s) => Object.keys(s).some((k) => k.startsWith('pass/')));// Left as the run had it: a gate below that reads the last frame's counters needs the profiler it turned on.- if (!(process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || process.env.ESTELLA_VERIFY_FRAME_DEBUG || PREPASS)) {+ if (!(process.env.ESTELLA_VERIFY_COUNTERS || process.env.ESTELLA_VERIFY_COUNTERS_MAX || process.env.ESTELLA_VERIFY_COUNTERS_MIN || process.env.ESTELLA_VERIFY_FRAME_DEBUG || PREPASS)) {await exec('window.__estellaHeadless.api.setCpuProfiling(false)');}const sums = scoped.map((s) => Object.entries(s).filter(([k]) => k.startsWith('pass/')).reduce((a, [, v]) => a + v, 0));diff --git a/tools/terrain-water-cost.mjs b/tools/terrain-water-cost.mjsindex 8233bc440..53874c5e0 100644--- a/tools/terrain-water-cost.mjs+++ b/tools/terrain-water-cost.mjs@@ -23,6 +23,7 @@ import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';import { existsSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';+import { deflateSync } from 'node:zlib';import { serveHost } from './lib/staticServer.mjs';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');@@ -83,6 +84,13 @@ const VARIANTS = [{ id: 'water-norings-msaa-1', label: 'no water surface, no multisampling', scene: (d) => { for (const z of comp(d, 'WaterZone')) z.data.rings = 0; }, config: quality('high', { msaaSamples: 1 }) },{ id: 'no-plants', label: 'no plants (world generation)', scene: dropEntities(...PLANTS) },{ id: 'no-terrain', label: 'no terrain (and no plants on it)', scene: dropEntities('Ground', ...PLANTS) },+ // The ground drawn from its virtual texture (baked surface pages): from level 1 (the default), from level 0, and with no plants over it.+ { id: 'vt', label: 'terrain virtual texture on', scene: (d) => { for (const t of comp(d, 'Terrain')) t.data.virtualTexture = true; } },+ { id: 'vt-from0', label: 'terrain virtual texture on, the nearest level too', scene: (d) => { for (const t of comp(d, 'Terrain')) Object.assign(t.data, { virtualTexture: true, virtualTextureFrom: 0 }); } },+ // The scene written back unchanged: what a variant that edits the scene costs before its edit does anything.+ { id: 'rewritten', label: 'the scene parsed and written back, nothing changed', scene: () => {} },+ { id: 'vt-none', label: 'terrain virtual texture on, no level drawn from it (what having it costs)', scene: (d) => { for (const t of comp(d, 'Terrain')) Object.assign(t.data, { virtualTexture: true, virtualTextureFrom: 15 }); } },+ { id: 'vt-no-plants', label: 'terrain virtual texture on, no plants', scene: (d) => { dropEntities(...PLANTS)(d); for (const t of comp(d, 'Terrain')) t.data.virtualTexture = true; } },{ id: 'no-shadows', label: 'the sun casts no shadow', scene: (d) => { for (const l of comp(d, 'Light')) l.data.meshShadows = false; } },// One effect at a time{ id: 'sky-off', label: 'sky atmosphere off', scene: dropEffects('skyAtmosphere') },@@ -164,6 +172,25 @@ const VARIANTS = [{ id: 'base-again', label: 'the scene again, to see the machine drift' },];+/** An RGBA picture as a PNG, its rows turned over: readPixels gives the bottom row first. */+function png(width, height, rgba) {+ const crcTable = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });+ const crc = (buf) => { let c = 0xffffffff; for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };+ const chunk = (type, data) => {+ const out = Buffer.alloc(12 + data.length);+ out.writeUInt32BE(data.length, 0);+ out.write(type, 4, 'latin1');+ data.copy(out, 8);+ out.writeUInt32BE(crc(out.subarray(4, 8 + data.length)), 8 + data.length);+ return out;+ };+ const raw = Buffer.alloc((width * 4 + 1) * height);+ for (let y = 0; y < height; y++) rgba.copy(raw, y * (width * 4 + 1) + 1, (height - 1 - y) * width * 4, (height - y) * width * 4);+ const head = Buffer.alloc(13);+ head.writeUInt32BE(width, 0); head.writeUInt32BE(height, 4); head[8] = 8; head[9] = 6;+ return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', head), chunk('IDAT', deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);+}+const median = (xs) => { const s = [...xs].sort((a, b) => a - b); return s[Math.floor(s.length / 2)]; };async function measure(server, original, variant, browser) {@@ -213,12 +240,15 @@ async function measure(server, original, variant, browser) {await c.step(frames, 1 / 60); sync();const ms = [];const gpuRuns = [];+ // Material bakes drawn while the frames are timed: a virtual texture still filling is work no steady frame does.+ const bakesBefore = c.render()['render.bakes.drawn'] ?? 0;for (let s = 0; s < samples; s++) {const t0 = performance.now();await c.step(frames, 1 / 60);sync();ms.push((performance.now() - t0) / frames);}+ const bakesTimed = (c.render()['render.bakes.drawn'] ?? 0) - bakesBefore;// After the wall-clock samples, so the pauses do not touch them: the browser delivers a timer query's answer// between tasks, not inside the burst that asked.for (let s = 0; s < passSamples; s++) {@@ -229,10 +259,20 @@ async function measure(server, original, variant, browser) {}const costs = c.costs();const cpu = costs.systems.reduce((a, x) => a + x.ms, 0);- return { ms, gpuRuns, counters: c.render(), cpu, systems: costs.systems, native: costs.native, size: [document.querySelector('canvas').width, document.querySelector('canvas').height], gl: !!gl };+ return { ms, gpuRuns, bakesTimed, counters: c.render(), cpu, systems: costs.systems, native: costs.native, size: [document.querySelector('canvas').width, document.querySelector('canvas').height], gl: !!gl };}, { frames: FRAMES, samples: SAMPLES, passSamples: PASSES ? SAMPLES : 0, detail: argv.includes('--detail') });- if (SHOTS) { await mkdir(SHOTS, { recursive: true }); await page.screenshot({ path: path.join(SHOTS, `${variant.id}-view${VIEW}.png`) }); }- return { ms: median(result.ms), gpu: gpuMedians(result.gpuRuns), cpu: result.cpu, systems: result.systems, native: result.native, min: Math.min(...result.ms), max: Math.max(...result.ms), settled, counters: result.counters, size: result.size, errors };+ // The engine's own frame, read back from the canvas: a page screenshot is the DOM, and a stepped game keeps its start screen over it.+ if (SHOTS) {+ await mkdir(SHOTS, { recursive: true });+ const shot = await page.evaluate(() => {+ const r = window.__estellaCooked.capture();+ let s = '';+ for (let i = 0; i < r.rgba.length; i += 0x8000) s += String.fromCharCode(...r.rgba.subarray(i, i + 0x8000));+ return { width: r.width, height: r.height, rgba: btoa(s) };+ });+ await writeFile(path.join(SHOTS, `${variant.id}-view${VIEW}.png`), png(shot.width, shot.height, Buffer.from(shot.rgba, 'base64')));+ }+ return { ms: median(result.ms), gpu: gpuMedians(result.gpuRuns), bakesTimed: result.bakesTimed, cpu: result.cpu, systems: result.systems, native: result.native, min: Math.min(...result.ms), max: Math.max(...result.ms), settled, counters: result.counters, size: result.size, errors };} finally {await context.close();}@@ -262,10 +302,13 @@ const original = {const worldFile = (await readdir(path.join(DIR, 'assets'))).filter((f) => f.endsWith('.esworld')).map((f) => path.join(DIR, 'assets', f))[0];original.world = await readFile(worldFile, 'utf8');const server = await serveHost(DIR);-const browser = await chromium.launch({+// A browser of its own for every variant: one that has already played a variant ran the next about 6 ms a frame slower at 1080p+// (measured 2026-11-13: the same scene, written back unchanged, 18.6 ms first and 24.9 ms second), so whatever ran second read dearer.+const launch = () => chromium.launch({headless: true,args: ['--use-angle=d3d11', '--enable-webgl', '--ignore-gpu-blocklist', '--disable-gpu-vsync', '--disable-frame-rate-limit', '--enable-unsafe-swiftshader'],});+const browser = await launch();const table = {};let adapter = '';try {@@ -282,7 +325,9 @@ try {// A page can die under a variant (the GPU process, memory); say so and carry on with the rest, once retried.let r;for (let attempt = 0; attempt < 2 && !r; attempt++) {- try { r = await measure(server, original, v, browser); } catch (e) { console.log(`${v.id.padEnd(17)} failed (${String(e.message).split(String.fromCharCode(10))[0]})${attempt === 0 ? ', retrying' : ''}`); }+ const fresh = await launch();+ try { r = await measure(server, original, v, fresh); } catch (e) { console.log(`${v.id.padEnd(17)} failed (${String(e.message).split(String.fromCharCode(10))[0]})${attempt === 0 ? ', retrying' : ''}`); }+ await fresh.close();}if (!r) { table[v.id] = { label: v.label, failed: true }; continue; }table[v.id] = { label: v.label, ...r };@@ -295,7 +340,7 @@ try {console.log(` gpu per pass (${v.id}): graph ${(r.gpu.graph ?? -1).toFixed(2)} ms, passes sum ${sum.toFixed(2)} ms, ${rows.length} passes`);for (const [k, x] of rows.slice(0, PASSES_TOP)) console.log(` ${k.slice(5).padEnd(34)} ${x.toFixed(2).padStart(7)} ms ${(100 * x / Math.max(sum, 1e-9)).toFixed(1).padStart(5)}%`);}- console.log(`${v.id.padEnd(17)} ${r.ms.toFixed(2).padStart(7)} ms [${r.min.toFixed(2)}..${r.max.toFixed(2)}] cpu ${r.cpu.toFixed(2)} draws ${r.counters['batch.draws'] ?? '?'} shadow ${r.counters['render.shadow.draws'] ?? '?'} tris ${((r.counters['render.triangles'] ?? 0) / 1e6).toFixed(2)}M prepass ${r.counters['render.prepass.draws'] ?? '?'} (meshes taken ${r.counters['render.prepass.taken'] ?? '?'}, cut-out ${r.counters['render.prepass.cutout'] ?? '?'}, bent ${r.counters['render.prepass.bent'] ?? '?'}, none ${r.counters['render.prepass.noProgram'] ?? '?'}) ${r.errors.length ? 'ERRORS ' + r.errors[0] : ''}`);+ console.log(`${v.id.padEnd(17)} ${r.ms.toFixed(2).padStart(7)} ms [${r.min.toFixed(2)}..${r.max.toFixed(2)}] cpu ${r.cpu.toFixed(2)} draws ${r.counters['batch.draws'] ?? '?'} shadow ${r.counters['render.shadow.draws'] ?? '?'} tris ${((r.counters['render.triangles'] ?? 0) / 1e6).toFixed(2)}M bakes timed ${r.bakesTimed ?? '?'} prepass ${r.counters['render.prepass.draws'] ?? '?'} (meshes taken ${r.counters['render.prepass.taken'] ?? '?'}, cut-out ${r.counters['render.prepass.cutout'] ?? '?'}, bent ${r.counters['render.prepass.bent'] ?? '?'}, none ${r.counters['render.prepass.noProgram'] ?? '?'}) ${r.errors.length ? 'ERRORS ' + r.errors[0] : ''}`);}} finally {await writeFile(path.join(DIR, 'assets/scenes/main.esscene'), original.scene);