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.

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.mjs
index 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.hpp
index 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 esengine
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 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 several
diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hpp
index 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.hpp
index 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.hpp
index 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.hpp
index 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.hpp
index 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 the
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
index 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 a
diff --git a/src/esengine/renderer/plugins/TrailPlugin.hpp b/src/esengine/renderer/plugins/TrailPlugin.hpp
index 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.hpp
index 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, so
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index 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