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.

perf(residency): a heavy cell, and the verdict on budgeting its arrival

esenginef71320202759
diff --git a/bench/residency/README.md b/bench/residency/README.md
index 49931abc9..a20cfb6a8 100644
--- a/bench/residency/README.md
+++ b/bench/residency/README.md
@@ -42,3 +42,40 @@ There is no priority, no prefetch and no budget yet, so a large cell arriving is
a hitch of its full size. `arrive` is measured over localhost: a real CDN adds
its own latency on top of the spawning cost, and only the spawning half of these
numbers is the engine's.
+
+## The heavy cell — is there an arrival nobody can split?
+
+`node bench/residency/heavy.mjs` builds ONE deliberately heavy cell out of the
+third-person sample's own imported assets — a skinned character with an animator,
+forty imported props at three levels of detail, two hundred physics bodies, 249
+entities — and reads two instruments rather than a stopwatch: the per-cell PHASES
+of the load, which run between frames and land on no system timer, and the
+per-frame cost of the frames it arrives on.
+
+### Measured 2026-09-05 (M-series Mac, WebGL2, 640×360, cold)
+
+```
+preparation (between frames, each phase atomic on the main thread):
+ spawn 7.00 ms ← the largest atomic phase there is
+ assets 6.20 ms
+ fetch 4.70 ms
+ delivery 19.00 ms issue → resident
+
+the frame it arrives on: 3.50 ms
+```
+
+**There is no unsplittable main-thread phase worth budgeting.** The largest is
+7 ms of ECS materialization for 249 entities including 200 bodies, and the frame
+the cell lands on costs 3.5 ms. A scheduler that sliced this would be buying
+complexity against a cost that is already inside a frame.
+
+**What IS worth hiding is the 19 ms of delivery.** Nineteen milliseconds is a
+player walking into a place that is not there yet for a dozen frames — and every
+part of it (fetch, asset acquisition, spawning) can happen before they arrive.
+That is the case for prefetch, and it is a latency argument, not a hitch one.
+
+One thing this cannot say: the arrival frame's 3.5 ms is a total, not a split
+between physics registration, render registration and animation. The per-system
+breakdown the driver asks for comes back empty here — the frame costs are
+engaged but not filled by the time the profile reads them. The verdict does not
+rest on it: a 3.5 ms frame cannot hide a 15 ms phase.
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjs
new file mode 100755
index 000000000..08d597db8
--- /dev/null
+++ b/bench/residency/heavy.mjs
@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file bench/residency/heavy.mjs — is there a cell arrival nobody can split?
+ *
+ * The cube world says no: 0.42 ms of spawn per cell and an arrival frame of
+ * 6 ms for twenty-five of them. What it cannot say is whether real content —
+ * an imported skin, several imported meshes, materials, textures, an animator,
+ * a few hundred bodies — hides a main-thread phase big enough to need a budget.
+ *
+ * So this builds ONE deliberately heavy cell out of assets that already exist
+ * (the third-person sample's), packages it, and reads two instruments rather
+ * than a stopwatch: the per-cell PHASES of the load, which run between frames
+ * and land on no system timer, and the per-SYSTEM cost of the frames the cell
+ * arrives on.
+ *
+ * node bench/residency/heavy.mjs
+ * node bench/residency/heavy.mjs --props 80 --bodies 400
+ */
+import { spawnSync } from 'node:child_process';
+import { rmSync, mkdirSync, writeFileSync, cpSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { runElectron } from '../../tools/lib/electronRun.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const WORK = path.join(ROOT, '.golden', 'bench-heavy');
+const LAUNCHER = path.join(ROOT, 'tools', 'launchers', 'residency-run.mjs');
+const SAMPLE = path.join(ROOT, 'examples', 'third-person-3d', 'assets', 'models');
+
+const flag = (name, fallback) => {
+ const at = process.argv.indexOf(`--${name}`);
+ return at >= 0 && process.argv[at + 1] ? process.argv[at + 1] : fallback;
+};
+
+const CELL = 600;
+const PROPS = Number(flag('props', '40'));
+const BODIES = Number(flag('bodies', '200'));
+
+const transform = (x, y, z, s = 1) => ({
+ type: 'Transform',
+ data: { position: { x, y, z }, scale: { x: s, y: s, z: s } },
+});
+const box = (r, g, b) => ({
+ type: 'MeshRenderer',
+ data: { mesh: 'builtin:cube', lit: true, opaque: true, cullBackfaces: true,
+ color: { r, g, b, a: 1 } },
+});
+const solid = (h) => ([
+ { type: 'RigidBody3D', data: { bodyType: 0 } },
+ { type: 'BoxCollider3D', data: { halfExtents: { x: h, y: h, z: h }, friction: 0.6 } },
+]);
+
+function project(dir) {
+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ mkdirSync(path.join(dir, 'assets', 'scenes'), { recursive: true });
+ mkdirSync(path.join(dir, 'src'), { recursive: true });
+ // The sample's own imported products, not a second content pipeline.
+ cpSync(SAMPLE, path.join(dir, 'assets', 'models'), { recursive: true });
+
+ const entities = [];
+ const push = (id, name, components, parent = null, children = []) =>
+ entities.push({ id, name, parent, children, visible: true, components });
+
+ // Persistent: everything residency never removes.
+ push(0, 'World', [transform(0, 0, 0),
+ { type: 'StreamedWorld', data: { cellSize: CELL } }]);
+ push(1, 'Camera', [transform(900, 400, 1400),
+ { type: 'Camera', data: { projectionType: 0, fov: 55, nearPlane: 10, farPlane: 8000,
+ isActive: true, priority: 0 } },
+ { type: 'WorldPersistent', data: {} }]);
+ push(2, 'Sun', [{ type: 'Transform', data: { position: { x: 0, y: 0, z: 0 },
+ rotation: { w: 0.834, x: -0.521, y: 0.182, z: 0 } } },
+ { type: 'Light', data: { type: 1, intensity: 1.05, enabled: true,
+ color: { r: 1, g: 0.96, b: 0.9, a: 1 } } },
+ { type: 'WorldPersistent', data: {} }]);
+ push(3, 'Ground', [transform(600, -20, 300, 1), ...solid(2000),
+ { type: 'MeshRenderer', data: { mesh: 'builtin:cube', lit: true, opaque: true,
+ color: { r: 0.3, g: 0.34, b: 0.3, a: 1 } } },
+ { type: 'WorldPersistent', data: {} }]);
+ // Parked outside every cell; the radius knob decides what it asks for.
+ push(4, 'Source', [transform(-1500, 60, 300),
+ { type: 'WorldStreamingSource', data: { loadRadius: 0, unloadRadius: 0, enabled: false } },
+ { type: 'WorldPersistent', data: {} }]);
+
+ // The heavy cell, at grid (1,0): a skin, imported meshes at three levels,
+ // materials, an animator, and a few hundred bodies.
+ let id = 100;
+ const skinRoot = id++;
+ const bone0 = id++;
+ const bone1 = id++;
+ const body = id++;
+ push(skinRoot, 'Hero', [transform(900, 60, 300),
+ { type: 'Animator', data: { controller: 'assets/models/locomotion.esanimator',
+ currentState: '', enabled: true } }],
+ null, [bone0, bone1, body]);
+ push(bone0, 'Bone0', [transform(0, 0, 0)], skinRoot);
+ push(bone1, 'Bone1', [transform(60, 0, 0)], skinRoot);
+ push(body, 'HeroBody', [transform(0, 0, 0),
+ { type: 'MeshRenderer', data: { mesh: 'assets/models/skinned-fade.esmesh',
+ lit: true, opaque: true, color: { r: 0.35, g: 0.75, b: 0.45, a: 1 } } },
+ { type: 'MeshSkin', data: { joints: [bone0, bone1] } }], skinRoot);
+
+ const LEVELS = ['rock-lod0', 'rock-lod1', 'rock-lod2'];
+ for (let n = 0; n < PROPS; n++) {
+ const x = 620 + (n % 8) * 22;
+ const z = 20 + Math.floor(n / 8) * 22;
+ push(id++, `Rock${n}`, [transform(x, 30, z, 1),
+ { type: 'MeshRenderer', data: { mesh: `assets/models/${LEVELS[n % 3]}.esmesh`,
+ lit: true, opaque: true,
+ color: { r: 0.5 + (n % 5) * 0.08, g: 0.5, b: 0.45, a: 1 } } },
+ { type: 'LODGroup', data: { lod1: 'assets/models/rock-lod1.esmesh',
+ lod2: 'assets/models/rock-lod2.esmesh',
+ lod1Size: 0.25, lod2Size: 0.11, cullSize: 0.02, hysteresis: 0.1 } }]);
+ }
+ for (let n = 0; n < BODIES; n++) {
+ const x = 610 + (n % 20) * 9;
+ const z = 300 + Math.floor(n / 20) * 9;
+ push(id++, `Body${n}`, [transform(x, 30, z, 0.2), box(0.6, 0.55, 0.45), ...solid(10)]);
+ }
+
+ writeFileSync(path.join(dir, 'assets', 'scenes', 'main.esscene'),
+ JSON.stringify({ version: 4, name: 'main', entities }, null, 1) + '\n');
+ writeFileSync(path.join(dir, 'assets', 'scenes', 'main.esscene.meta'),
+ JSON.stringify({ uuid: randomUUID(), version: '2.0', type: 'scene', importer: {} }) + '\n');
+ writeFileSync(path.join(dir, 'project.esproject'), JSON.stringify({
+ formatVersion: '1', name: 'Heavy Cell', description: 'One deliberately heavy cell.',
+ tag: '3D', version: '0.1.0', defaultScene: 'assets/scenes/main.esscene',
+ 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 type { World, InputState } from 'esengine';
+
+const radiusSystem = defineSystem(
+ [Res(Input), GetWorld()],
+ (input: InputState, world: World) => {
+ const on = input.isKeyPressed('Digit1');
+ if (!on && !input.isKeyPressed('Digit0')) return;
+ const source = world.findEntityByName('Source');
+ if (source === null) return;
+ world.update(source, WorldStreamingSource, (s) => {
+ s.loadRadius = on ? 3000 : 0;
+ s.unloadRadius = on ? 3200 : 0;
+ s.enabled = on;
+ });
+ },
+ { name: 'RadiusSystem' },
+);
+addSystemToSchedule(Schedule.Update, radiusSystem);
+`);
+ writeFileSync(path.join(dir, 'tsconfig.json'), JSON.stringify({
+ compilerOptions: {
+ target: 'ES2020', module: 'ESNext', moduleResolution: 'bundler', strict: true,
+ esModuleInterop: true, skipLibCheck: true, noEmit: true,
+ paths: { esengine: ['./.esengine/sdk/index.d.ts'] },
+ },
+ include: ['src/**/*'],
+ }, null, 2) + '\n');
+ return dir;
+}
+
+function main() {
+ if (!existsSync(SAMPLE)) {
+ console.error(`✗ the sample's imported assets are not here: ${SAMPLE}`);
+ process.exit(2);
+ }
+ rmSync(WORK, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ mkdirSync(WORK, { recursive: true });
+ const src = project(path.join(WORK, 'src'));
+ const out = path.join(WORK, 'web');
+ const built = spawnSync(process.execPath, [
+ path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', src,
+ '--platform', 'web', '--out', out,
+ ], { encoding: 'utf8', cwd: ROOT });
+ if (built.status !== 0) {
+ console.error(`✗ the heavy world did not package:\n${(built.stderr || built.stdout || '').slice(-900)}`);
+ process.exit(1);
+ }
+
+ const script = path.join(WORK, 'probe.json');
+ writeFileSync(script, JSON.stringify([
+ { do: 'step', frames: 30 },
+ // One frame at a time from the gesture, so the arrival is a row and not
+ // an average, with a system breakdown wherever a frame is expensive.
+ { do: 'frames', as: 'arrival', key: 'Digit1', count: 240, costsAbove: 1.0 },
+ ], null, 2));
+ const run = runElectron([LAUNCHER, '--dir', out, '--script', script, '--w', '640', '--h', '360'],
+ { encoding: 'utf8', cwd: ROOT });
+
+ const readings = {};
+ 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 frames = readings.profile;
+ const delivery = readings.delivery;
+ if (!frames) {
+ console.error(`✗ nothing was measured — ${(run.stdout || run.stderr || '').slice(-500)}`);
+ process.exit(1);
+ }
+
+ const heavy = frames.filter((f) => f.ms > 1.0);
+ const arrival = frames.find((f, i) => i > 0 && frames[i - 1].resident === 0 && f.resident > 0);
+ console.log(`\nheavy cell — 1 skin, ${PROPS} imported props, ${BODIES} bodies\n`);
+ console.log(' preparation (between frames, no system timer holds it):');
+ for (const [cell, v] of Object.entries(delivery ?? {})) {
+ for (const [phase, ms] of Object.entries(v.phases).sort((a, b) => b[1] - a[1])) {
+ console.log(` ${phase.padEnd(8)} ${ms.toFixed(2).padStart(8)} ms`);
+ }
+ console.log(` ${'delivery'.padEnd(8)} ${v.deliveryMs.toFixed(2).padStart(8)} ms (issue → resident, ${cell})`);
+ }
+ console.log('\n the frames it cost, by system:');
+ for (const f of heavy.slice(0, 12)) {
+ const at = frames.indexOf(f);
+ const top = (f.costs ?? []).slice(0, 4).map((c) => `${c.name} ${c.ms.toFixed(2)}`).join(', ');
+ console.log(` f${String(at).padEnd(4)} ${f.ms.toFixed(2).padStart(6)} ms ent=${f.entities} bodies=${f.bodies}${top ? ` | ${top}` : ''}`);
+ }
+ const worst = Math.max(...frames.map((f) => f.ms));
+ const spawn = Object.values(delivery ?? {})[0]?.phases?.spawn ?? 0;
+ console.log(`\n largest single frame ${worst.toFixed(1)} ms; largest atomic preparation phase `
+ + `${Math.max(spawn, ...Object.values(Object.values(delivery ?? {})[0]?.phases ?? { a: 0 })).toFixed(1)} ms`);
+ console.log(` arrival landed on frame ${arrival ? frames.indexOf(arrival) : '(none)'}\n`);
+}
+
+main();
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 1945812fc..1acb4a189 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -360,7 +360,8 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
app.getResource(VideoPlayer).setRefResolver((ref) => backend.resolveUrl(resolveRef(ref)));
}
mergeSceneTextureImportSettings(sceneAssets, sceneData, source.resolveRef ?? ((r) => r));
- const assetResult = await sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true });
+ const assetResult = await timed('assets',
+ () => sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true }));
sceneAssets.resolveSceneAssetPaths(sceneData, assetResult);
applyTextureMetadata(sceneData, assetResult.textureHandles, source.resolveRef ?? ((ref) => ref));
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index 577f910e2..b89406fea 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -249,6 +249,11 @@ async function main() {
target.dispatchEvent(e);
if (target !== window) window.dispatchEvent(new KeyboardEvent(type, { code, key: code, bubbles: true }));
};
+ // Stats need a frame to fill, so they are engaged before the first
+ // sample rather than by the first expensive one — which is the frame
+ // whose breakdown matters most.
+ window.__estellaCooked.costs(1);
+ await window.__estellaCooked.step(1, 1 / 60);
${step.key ? `send('keydown', ${JSON.stringify(step.key)});` : ''}
const out = [];
for (let i = 0; i < ${step.count ?? 120}; i++) {