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
feat(renderer): the arrival's render cost is MeshPlugin's first look at what arrived
esenginea0a215f22686
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjsindex c7e351faf..b1dad6724 100755--- a/bench/residency/heavy.mjs+++ b/bench/residency/heavy.mjs@@ -131,24 +131,39 @@ function project(dir) {designResolution: { width: 640, height: 360 }, spineVersion: 'none',}, null, 2) + '\n');writeFileSync(path.join(dir, 'src', 'main.ts'), `-import { addSystemToSchedule, Schedule, defineSystem, GetWorld, Res, Input, WorldStreamingSource } from 'esengine';+import { addSystemToSchedule, Schedule, defineSystem, GetWorld, Res, Input, Transform, WorldStreamingSource } from 'esengine';import type { World, InputState } from 'esengine';+// Latched, because a gesture is one frame and residency is asked every frame: a+// system that reads the key alone would give the cell back the frame after.+let ready = false;+let want = false;+const radiusSystem = defineSystem([Res(Input), GetWorld()],(input: InputState, world: World) => {- // Digit2 readies without wanting; Digit1 wants. Pressed in that order the- // arrival is a HIT, and pressing Digit1 alone is the miss.- const ready = input.isKeyPressed('Digit2');- const want = input.isKeyPressed('Digit1');- if (!ready && !want) return;+ if (input.isKeyPressed('Digit2')) ready = true;+ if (input.isKeyPressed('Digit1')) want = true;const source = world.findEntityByName('Source');- if (source === null) return;- world.update(source, WorldStreamingSource, (s) => {- s.loadRadius = want ? 3000 : 0;- s.prefetchRadius = ready ? 3000 : 0;- s.unloadRadius = 3200;- s.enabled = true;+ if (source !== null && (ready || want)) {+ world.update(source, WorldStreamingSource, (s) => {+ s.loadRadius = want ? 3000 : 0;+ s.prefetchRadius = ready ? 3000 : 0;+ s.unloadRadius = 3200;+ s.enabled = true;+ });+ }+ // Turning the camera away and back is what separates "publication made+ // the renderer work" from "seeing it for the first time did".+ const away = input.isKeyPressed('Digit3');+ const back = input.isKeyPressed('Digit4');+ if (!away && !back) return;+ const camera = world.findEntityByName('Camera');+ if (camera === null) return;+ world.update(camera, Transform, (t) => {+ t.rotation.x = 0; t.rotation.z = 0;+ t.rotation.y = away ? 1 : 0;+ t.rotation.w = away ? 0 : 1;});},{ name: 'RadiusSystem' },@@ -187,26 +202,31 @@ function main() {// Two ways into the SAME cell, each from a cold cache, because the question// "what does prefetch cost" has no answer from one of them: readying early// does not make the work cheaper, it moves WHEN it is paid.+ // One frame at a time, every one broken down: an arrival costs its excess+ // over a steady state, and a steady state nobody broke down is a number to+ // subtract from rather than one to attribute.+ const profile = (as, key) => ({ do: 'frames', as, key, count: 240, costsAbove: 0 });const arms = [- ['miss', [- { do: 'step', frames: 30 },- // One frame at a time, every one broken down: an arrival costs its- // excess over a steady state, and a steady state nobody broke down is- // a number to subtract from rather than one to attribute.- { do: 'frames', as: 'arrival', key: 'Digit1', count: 240, costsAbove: 0 },- ]],- ['hit', [- { do: 'step', frames: 30 },- // Readied and SETTLED first: `arrive` waits out `preparing`, so the- // demand below meets a cell that is already `prepared`.- { do: 'arrive', as: 'primed', key: 'Digit2' },- { do: 'frames', as: 'arrival', key: 'Digit1', count: 240, costsAbove: 0 },- ]],+ ['miss', [{ do: 'step', frames: 30 }, profile('arrival', 'Digit1')]],+ // Readied and SETTLED first: `arrive` waits out `preparing`, so the+ // demand below meets a cell that is already `prepared`.+ ['hit', [{ do: 'step', frames: 30 }, { do: 'arrive', as: 'primed', key: 'Digit2' },+ profile('arrival', 'Digit1')]],+ // Nothing ever arrives. The control for every spike below: a renderer+ // that produces one of these on its own is not producing it for us.+ ['zero', [{ do: 'step', frames: 30 }, profile('arrival', null)]],+ // Published with the camera turned away, then turned back. Which of the+ // two profiles carries the spike is the whole experiment: publication+ // bookkeeping shows in the first, first visibility in the second.+ ['blind', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },+ profile('published', 'Digit1'), profile('revealed', 'Digit4')]],];for (const [arm, steps] of arms) {- const { frames, delivery } = drive(out, arm, steps);- report(arm, frames, delivery);+ const runs = drive(out, arm, steps);+ for (const [as, { frames, delivery }] of runs) {+ report(`${arm}${runs.size > 1 ? `/${as}` : ''}`, frames, delivery);+ }}console.log('');process.exit(failedTotal === 0 ? 0 : 1);@@ -219,20 +239,31 @@ function drive(out, name, steps) {const script = path.join(WORK, `${name}.json`);writeFileSync(script, JSON.stringify(steps, null, 2));const run = runElectron([LAUNCHER, '--dir', out, '--script', script, '--w', '640', '--h', '360'],- { encoding: 'utf8', cwd: ROOT });-- const readings = {};+ // Node's 1 MB default truncates a per-frame profile mid-JSON, and a+ // truncated line parses as nothing — which this bench then reports as an+ // engine that produced no measurement.+ { encoding: 'utf8', cwd: ROOT, maxBuffer: 256 * 1024 * 1024 });++ // Keyed by the step's `as`, because an arm may profile twice — publishing+ // and revealing are two events, and one overwriting the other is how the+ // experiment that separates them stops separating them.+ const runs = new Map();for (const line of (run.stdout || '').split('\n')) {- const at = Math.max(line.indexOf('profile '), line.indexOf('delivery '));- if (at < 0) continue;- const kind = line.slice(at, line.indexOf(' ', at));- try { readings[kind] = JSON.parse(line.slice(line.indexOf(line.includes('profile') && kind === 'profile' ? '[' : '{', at))); } catch { /* partial */ }+ const match = /^(profile|delivery) ([^:]+): /.exec(line);+ if (!match) continue;+ const [, kind, as] = match;+ if (!runs.has(as)) runs.set(as, { frames: null, delivery: null });+ try {+ const body = line.slice(line.indexOf(kind === 'profile' ? '[' : '{', match[0].length - 1));+ runs.get(as)[kind === 'profile' ? 'frames' : 'delivery'] = JSON.parse(body);+ } catch { /* partial line */ }}- if (!readings.profile) {+ for (const [as, r] of runs) if (!r.frames) runs.delete(as);+ if (runs.size === 0) {console.error(`✗ ${name}: nothing was measured — ${(run.stdout || run.stderr || '').slice(-500)}`);process.exit(2);}- return { frames: readings.profile, delivery: readings.delivery };+ return runs;}function report(arm, frames, delivery) {@@ -248,10 +279,24 @@ function report(arm, frames, delivery) {console.log(` ${ok ? '✓' : '✗'} ${claim}${detail ? ` — ${detail}` : ''}`);};- // Index 0 included: both arms begin with nothing resident, and the hit path- // publishes inside the frame that asked — a finder skipping frame 0 cannot- // see the one arrival prefetch exists to produce.- const arrivalAt = frames.findIndex((f) => f.resident > 0);+ // Three events, not one: need (the gesture), publish (the entities exist),+ // visible (the renderer first ACCEPTS them). Anchoring on publish measures+ // the wrong event, and a spike outside such a window is a definition.+ const publishAt = frames.findIndex((f) => f.resident > 0);+ const drawn = (f) => f.drawn ?? 0;+ const floor = drawn(frames[0]);+ const peak = Math.max(...frames.map(drawn));+ const visibleAt = peak > floor + 10+ ? frames.findIndex((f) => drawn(f) >= floor + (peak - floor) * 0.5)+ : -1;+ // An arm where nothing ever arrives is the control, and it has no window.+ // Reported as such rather than as an arrival of zero frames: those are two+ // different statements and only one of them is true here.+ const arrivalAt = visibleAt >= 0 ? visibleAt : publishAt;+ const arrived = arrivalAt >= 0;+ console.log(` need f0 → publish ${publishAt < 0 ? '(never)' : `f${publishAt}`}`+ + ` → first renderable accepted ${visibleAt < 0 ? '(never)' : `f${visibleAt}`}`+ + ` (${floor} → ${peak} drawn)`);// MEANS, and means for both halves. A median wall time against mean domain// times is two baselines, and the excess arithmetic below then does not// close — it reported 112% of an excess it had mis-subtracted.@@ -336,15 +381,23 @@ function report(arm, frames, delivery) {}console.log(`\n realization — ECS-visible → actually drawn. Steady state ${baseline.toFixed(2)} ms/frame, `- + `the cell became visible on frame ${arrivalAt < 0 ? '(none)' : arrivalAt}\n`);- console.log(' frame wall systems accounted | by domain');- for (const f of window) {+ + `${arrived ? `anchored on f${arrivalAt}` : 'NOTHING ARRIVED — this is the control'}\n`);+ console.log(' frame wall systems collect drawn | by domain');+ // Beyond the window: whether the first frame's collect is a ONE-OFF or the+ // new steady cost is what one frame cannot tell apart.+ const shown = arrived+ ? frames.slice(arrivalAt, Math.max(arrivalAt + window.length, arrivalAt + 12))+ : [];+ for (const f of shown) {const domains = byDomain(f);- const accounted = [...domains.values()].reduce((a, b) => a + b, 0);- const top = [...domains].sort((a, b) => b[1] - a[1]).filter(([, ms]) => ms >= 0.01).slice(0, 4)+ const top = [...domains].sort((a, b) => b[1] - a[1]).filter(([, ms]) => ms >= 0.01).slice(0, 3).map(([d, ms]) => `${d} ${ms.toFixed(2)}`).join(', ');+ const collect = f.collect ?? 0;+ const inWindow = frames.indexOf(f) < arrivalAt + window.length;console.log(` f${String(frames.indexOf(f)).padEnd(6)}${f.ms.toFixed(2).padStart(7)}`- + `${accounted.toFixed(2).padStart(9)}${pct(accounted, f.ms).padStart(10)} | ${top}`);+ + `${[...domains.values()].reduce((a, b) => a + b, 0).toFixed(2).padStart(9)}`+ + `${collect.toFixed(2).padStart(9)}${String(drawn(f)).padStart(9)}`+ + ` |${inWindow ? '' : ' ·'} ${top}`);}const wall = window.reduce((a, f) => a + f.ms, 0);const accounted = window.reduce((a, f) => a + sumDomains(f), 0);@@ -407,6 +460,29 @@ function report(arm, frames, delivery) {if (!fits) failed++;void failed;+ const spikes = frames.map((f, i) => ({ i, f }))+ .filter(({ f }) => f.ms > baseline + 4)+ .sort((a, b) => b.f.ms - a.f.ms).slice(0, 6);+ if (spikes.length > 0) {+ console.log('\n every frame more than 4 ms above steady state:');+ for (const { i, f } of spikes) {+ const own = arrived && i >= arrivalAt && i < arrivalAt + window.length;+ console.log(` f${String(i).padEnd(5)}${f.ms.toFixed(2).padStart(7)} ms`+ + ` collect ${(f.collect ?? 0).toFixed(2).padStart(6)}`+ + ` drawn ${String(drawn(f)).padStart(5)}`+ + ` ${own ? '(the arrival)' : '(NOT the arrival)'}`);+ // A spike with no collect in it is a different mechanism wearing the+ // same shape, and naming it needs its own scopes rather than the+ // window's — which is what made it look like a delayed arrival.+ const inside = [+ ...(f.scopes ?? []).map((c) => [`js ${c.name}`, c.ms]),+ ...Object.entries(f.native ?? {}).map(([n, ms]) => [`cpp ${n}`, ms]),+ ].sort((a, b) => b[1] - a[1]).filter(([, ms]) => ms >= 0.1).slice(0, 5);+ for (const [n, ms] of inside) {+ console.log(` ${n.padEnd(30)}${ms.toFixed(2).padStart(7)} ms`);+ }+ }+ }const worstAt = frames.reduce((best, f, i) => (f.ms > frames[best].ms ? i : best), 0);const worst = frames[worstAt];console.log(`\n largest single frame of the whole run: f${worstAt} at ${worst.ms.toFixed(1)} ms`diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex c48016785..db0107819 100644--- a/src/esengine/renderer/RenderTypePlugin.hpp+++ b/src/esengine/renderer/RenderTypePlugin.hpp@@ -292,6 +292,15 @@ public:virtual bool drawsScreenUI() const { return false; }virtual void collect(RenderCollectContext& ctx) = 0;++ /**+ * @brief What this plugin's collect is called in a frame profile.+ *+ * @details A literal: the profiler keys scopes by content and keeps the+ * pointer. A type that does not answer is reported as `other`+ * rather than folded into a neighbour, whose cost it would become.+ */+ virtual const char* collectScope() const { return "render.collect.other"; }};} // namespace esenginediff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 2e6219406..dccaf7865 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1555,13 +1555,16 @@ bool RenderFrame::visibleToCamera(i32 layer, const glm::vec3& center,void RenderFrame::collectAll(ecs::Registry& registry) {ES_PROFILE_SCOPE("render.collect");- buildClipState();- collectLights(registry);+ // Split because "collect is expensive" names no mechanism: planning shadows,+ // gathering lights and walking one render type's population are different+ // work that a single total cannot be told apart by.+ { ES_PROFILE_SCOPE("render.collect.clip"); buildClipState(); }+ { ES_PROFILE_SCOPE("render.collect.lights"); collectLights(registry); }// Decided here, drawn by the graph. Nothing in this function may touch the// device: the frame reaches the host as several calls with its own draws// between them, and a pass opened here would swallow them.- buildShadowPlan(registry);- declareShadowPass(registry);+ { ES_PROFILE_SCOPE("render.collect.shadowPlan"); buildShadowPlan(registry); }+ { ES_PROFILE_SCOPE("render.collect.shadowDeclare"); declareShadowPass(registry); }auto ctx = makeContext();@@ -1572,8 +1575,11 @@ void RenderFrame::collectAll(ecs::Registry& registry) {// through a view matrix puts a HUD wherever the view happens to be looking.collectCtx.screen_ui = screen_domain_;collectCtx.lod = {view_id_, &lod_view_state_, &lod_counts_};- collectSky(collectCtx);- for (auto& plugin : plugins_) plugin->collect(collectCtx);+ { ES_PROFILE_SCOPE("render.collect.sky"); collectSky(collectCtx); }+ for (auto& plugin : plugins_) {+ ES_PROFILE_SCOPE(plugin->collectScope());+ plugin->collect(collectCtx);+ }// The other half of what the frame cost: what it did NOT draw. Accumulated// like the per-type counts beside it, so a frame composited from severaldiff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hppindex 545ef8075..aaa41d110 100644--- a/src/esengine/renderer/plugins/MeshPlugin.hpp+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp@@ -25,6 +25,7 @@ public:/// renderable's shadow is ShadowCaster2D's to cast, not the map's.bool castsShadows() const override { return true; }void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.mesh"; }private:std::vector<BatchVertex> scratch_; ///< Reused per mesh; amortizes the transform buffer.diff --git a/src/esengine/renderer/plugins/ParticlePlugin.hpp b/src/esengine/renderer/plugins/ParticlePlugin.hppindex e86855eb4..ed69e4f0e 100644--- a/src/esengine/renderer/plugins/ParticlePlugin.hpp+++ b/src/esengine/renderer/plugins/ParticlePlugin.hpp@@ -25,6 +25,7 @@ public:// follows the tree into the screen domain too.bool drawsScreenUI() const override { return true; }void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.particle"; }private:particle::ParticleSystem* particle_system_ = nullptr;diff --git a/src/esengine/renderer/plugins/ShapePlugin.hpp b/src/esengine/renderer/plugins/ShapePlugin.hppindex 47b9c0bf3..603ee54c4 100644--- a/src/esengine/renderer/plugins/ShapePlugin.hpp+++ b/src/esengine/renderer/plugins/ShapePlugin.hpp@@ -14,6 +14,7 @@ public:void shutdown() override;void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.shape"; }private:struct ShapeVertex {diff --git a/src/esengine/renderer/plugins/SpritePlugin.hpp b/src/esengine/renderer/plugins/SpritePlugin.hppindex d53dc532b..1616a2cca 100644--- a/src/esengine/renderer/plugins/SpritePlugin.hpp+++ b/src/esengine/renderer/plugins/SpritePlugin.hpp@@ -14,6 +14,7 @@ public:// tree is — and has to be drawn by the pass that owns those coordinates.bool drawsScreenUI() const override { return true; }void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.sprite"; }private:// Sprite-only: tiling repeats the texture across the quad. UI has no tiled variant,diff --git a/src/esengine/renderer/plugins/TextPlugin.hpp b/src/esengine/renderer/plugins/TextPlugin.hppindex 92376bc7f..bcc75cd10 100644--- a/src/esengine/renderer/plugins/TextPlugin.hpp+++ b/src/esengine/renderer/plugins/TextPlugin.hpp@@ -16,6 +16,7 @@ namespace ecs { struct BitmapText; }class TextPlugin : public BatchPlugin {public:void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.text"; }private:// Glyph quads cached in fontSize-applied, scale-free units relative to thediff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.hppindex 721111c89..d0c7347a9 100644--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp@@ -22,6 +22,7 @@ public:void setTilemapSystem(tilemap::TilemapSystem* system) { tilemap_system_ = system; }void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.tilemap"; }private:// Per-tileset-slot geometry for one chunk. A multi-tileset layer splits adiff --git a/src/esengine/renderer/plugins/TrailPlugin.hpp b/src/esengine/renderer/plugins/TrailPlugin.hppindex 1497d21d7..0276702ac 100644--- a/src/esengine/renderer/plugins/TrailPlugin.hpp+++ b/src/esengine/renderer/plugins/TrailPlugin.hpp@@ -30,6 +30,7 @@ public:void setTrailSystem(trail::TrailSystem* system) { trail_system_ = system; }void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.trail"; }private:trail::TrailSystem* trail_system_ = nullptr;diff --git a/src/esengine/renderer/plugins/UIElementPlugin.hpp b/src/esengine/renderer/plugins/UIElementPlugin.hppindex 1a9a5f9d3..d976774bc 100644--- a/src/esengine/renderer/plugins/UIElementPlugin.hpp+++ b/src/esengine/renderer/plugins/UIElementPlugin.hpp@@ -12,6 +12,7 @@ class UIElementPlugin : public BatchPlugin {public:bool drawsScreenUI() const override { return true; }void collect(RenderCollectContext& ctx) override;+ const char* collectScope() const override { return "render.collect.ui"; }// UI draws above world content: its sort layer is offset past the world// layer range. The SDK's own text renderer puts quads at the same base, sodiff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjsindex 5b8337070..fe9e90f19 100644--- a/tools/launchers/residency-run.mjs+++ b/tools/launchers/residency-run.mjs@@ -270,19 +270,30 @@ async function main() {// the pipe to the bench (which reads as "nothing was measured").const costs = window.__estellaCooked.costs();row.on = costs.on;+ // Two numbers, not the whole table: which frame first draws a cell's+ // renderables is a COUNT crossing every frame needs, and a full table+ // per frame overruns the pipe to the bench.+ const counters = window.__estellaCooked.render();+ row.drawn = (counters['render.meshes'] ?? 0) + (counters['render.sprites'] ?? 0)+ + (counters['render.text'] ?? 0) + (counters['render.shapes'] ?? 0)+ + (counters['render.particles'] ?? 0);+ row.collect = costs.native['render.collect'] ?? 0;row.domains = {};for (const c of costs.systems) row.domains[c.domain] = (row.domains[c.domain] ?? 0) + c.ms;for (const d of Object.keys(row.domains)) row.domains[d] = Math.round(row.domains[d] * 1000) / 1000;- // The per-SYSTEM detail only where it can matter: which system inside a- // domain is a question worth asking of an expensive frame alone. The- // scopes ride with it — they nest INSIDE systems, so a reader adds one- // list or the other and never both.+ // Layered by size. Scopes are a handful of rows every frame may need;+ // the system list and counter table are dozens each, and 240 frames of+ // those overrun the pipe (arriving as "nothing was measured").if (ms > ${step.costsAbove ?? 1.5}) {- row.costs = costs.systems.filter((c) => c.ms > 0.01);row.scopes = costs.scopes.filter((c) => c.ms > 0.01);row.native = Object.fromEntries(Object.entries(costs.native).filter(([, v]) => v > 0.01));}+ if (ms > ${step.detailAbove ?? 2.0}) {+ row.costs = costs.systems.filter((c) => c.ms > 0.01);+ row.counters = Object.fromEntries(+ Object.entries(counters).filter(([, v]) => v > 0));+ }out.push(row);// A macrotask turn between frames. Awaiting a step only drains// MICROtasks, and a cell arrives over the network — so a loop without