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.

39.8 KB
Raw Blame
#!/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, readFileSync, 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;
/** The one cell this fixture cooks, as residency registers it. */
const CELL_NAME = 'main.cell_1_0';
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, 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) => {
        if (input.isKeyPressed('Digit2')) ready = true;
        if (input.isKeyPressed('Digit1')) want = true;
        const source = world.findEntityByName('Source');
        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' },
);
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);
    }

    // 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 }, 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')]],
        // Does a PREPARED cell know what a published one needs? Both derivations
        // run on the same cell and their key SETS are compared — a count that
        // matched by luck would not be an equivalence.
        ['equivalence', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },
                         profile('published', 'Digit1'),
                         { do: 'prewarm', as: 'document', cell: CELL_NAME, from: 'document' },
                         { do: 'prewarm', as: 'entities', cell: CELL_NAME }]],
        // The same walk, with the programs readied while the camera is still
        // away. If first visibility then costs what a warm frame costs, the
        // hitch was the compile and readying it early is where it belongs.
        ['prewarmed', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },
                       profile('published', 'Digit1'),
                       { do: 'prewarm', as: 'ready', cell: CELL_NAME },
                       profile('revealed', 'Digit4')]],
        // The real shape: readied while the cell is only PREPARED, from its own
        // document, before a single entity of it exists. Then demanded, which on
        // this path publishes and becomes visible in the same frame.
        ['readied', [{ do: 'step', frames: 30 },
                     { do: 'arrive', as: 'primed', key: 'Digit2' },
                     { do: 'prewarm', as: 'ready', cell: CELL_NAME, from: 'document' },
                     profile('arrival', 'Digit1')]],
    ];

    // `--arms hit,blind` narrows a remeasure to the question being asked. Each
    // arm is its own Electron, so running the ones nobody is reading is minutes
    // spent on a number nobody will look at.
    const wanted = flag('arms', '').split(',').filter(Boolean);
    for (const [arm, steps] of arms.filter(([a]) => wanted.length === 0 || wanted.includes(a))) {
        const runs = drive(out, arm, steps);
        for (const [as, { frames, delivery }] of runs) {
            report(`${arm}${runs.size > 1 ? `/${as}` : ''}`, frames, delivery);
        }
        for (const [as, ready] of prewarmed.get(arm) ?? []) {
            console.log(`\n  readying ${arm}/${as} took ${ready.ms.toFixed(2)} ms`
                + ` — ${ready.compiles} compile(s) of ${ready.uniqueKeys} unique key(s)`
                + ` over ${ready.asks} ask(s) for ${ready.entities} renderable(s);`
                + ` ${ready.materialCompiles} material compile(s) of ${ready.materialAsks} ask(s)`
                + `  keys ${keySetText(ready)}`);
        }
        const both = prewarmed.get(arm);
        if (both?.has('document') && both.has('entities')) {
            const doc = both.get('document');
            const live = both.get('entities');
            const same = sameKeys(doc, live);
            failedTotal += same ? 0 : 1;
            console.log(`\n  ${same ? '✓' : '✗'} what a PREPARED cell knows it will need equals`
                + ` what its published entities ask for`
                + ` — ${keySetText(doc)} from the document, ${keySetText(live)} from the world`);
            const materials = doc.materialAsks === live.materialAsks;
            failedTotal += materials ? 0 : 1;
            console.log(`  ${materials ? '✓' : '✗'} and the material-owned path is enumerated the`
                + ` same both ways — ${doc.materialAsks} against ${live.materialAsks} ask(s)`);
        }
    }
    console.log('');
    process.exit(failedTotal === 0 ? 0 : 1);
}

let failedTotal = 0;
/** What readying an arm's programs early cost, by arm. */
const prewarmed = new Map();

/** Run one arm in its own Electron, so each pays for its own cold cache. */
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'],
        // 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 ready = /^prewarm ([^:]+): (.*)$/.exec(line);
        if (ready) {
            try {
                if (!prewarmed.has(name)) prewarmed.set(name, new Map());
                prewarmed.get(name).set(ready[1], JSON.parse(ready[2]));
            } catch { /* partial */ }
            continue;
        }
        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 rest = line.slice(match[0].length);
            // A profile arrives as a path, because stdout cannot carry it whole.
            const body = kind === 'profile' && !rest.startsWith('[')
                ? readFileSync(rest.trim(), 'utf8')
                : line.slice(line.indexOf(kind === 'profile' ? '[' : '{', match[0].length - 1));
            runs.get(as)[kind === 'profile' ? 'frames' : 'delivery'] = JSON.parse(body);
        } catch { /* partial line */ }
    }
    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 runs;
}

/**
 * What may be left unnamed before an instrument is not closed.
 *
 * PER FRAME for the frame accounting, because the residual IS the per-frame cost
 * outside every system accumulated over the window — a fixed budget would pass a
 * short window and fail a long one for the same engine.
 */
const RESIDUAL_MS = 0.6;
const RESIDUAL_MS_PER_FRAME = 0.15;

function report(arm, frames, delivery) {

    console.log(`\n${'='.repeat(78)}\nheavy cell, ${arm.toUpperCase()} — `
        + `${arm === 'hit' ? 'readied before it was wanted' : 'wanted before anything readied it'}`
        + ` — 1 skin, ${PROPS} imported props, ${BODIES} bodies\n`);

    let failed = 0;
    const check = (ok, claim, detail) => {
        if (!ok) failed++;
        failedTotal += ok ? 0 : 1;
        console.log(`  ${ok ? '✓' : '✗'} ${claim}${detail ? ` — ${detail}` : ''}`);
    };

    // 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)`);
    // The upload's cost over EVERY frame, not the frames that happened to clear the
    // spike bar. The stall it exists to catch fires about six times in a thousand
    // frames, so "did this run show one" is a coin toss and a rate is not.
    {
        const up = frames.map((f) => (f.native ?? {})['render.finalize.upload'] ?? 0);
        const over = (t) => up.filter((v) => v >= t).length;
        const first = up.findIndex((v) => v >= 1);
        console.log(`  upload over ${up.length} frames: >=1ms ${over(1)}, >=4ms ${over(4)},`
            + ` max ${Math.max(...up).toFixed(2)} ms, first at `
            + `${first < 0 ? 'never' : `f${first}`} — see README, Transient Upload Stall`);
    }
    // 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.
    const settled = frames.slice(-60);
    const mean = (values) => values.reduce((a, b) => a + b, 0) / (values.length || 1);
    const baseline = mean(settled.map((f) => f.ms));
    const baselineSystems = mean(settled.map((f) => sumDomains(f)));
    const baselineDomains = new Map();
    for (const f of settled) {
        for (const [domain, ms] of byDomain(f)) {
            baselineDomains.set(domain, (baselineDomains.get(domain) ?? 0) + ms / settled.length);
        }
    }
    // Closes on quiet, not on a count. Realization lands a variable number of
    // frames after publication, so a fixed window is one that sometimes misses
    // the thing it exists to measure.
    const QUIET = 3;
    const window = [];
    if (arrivalAt >= 0) {
        let calm = 0;
        for (let i = arrivalAt; i < frames.length && window.length < 40; i++) {
            window.push(frames[i]);
            calm = frames[i].ms <= baseline + 0.3 ? calm + 1 : 0;
            if (calm >= QUIET) break;
        }
    }

    // On every frame of the window, not only the expensive ones: a cheap first
    // visibility is exactly where a compile is easiest to miss.
    const compiledInRun = Math.max(0, ...frames.map((f) => f.compiles ?? 0));
    const compiledInWindow = Math.max(0, ...window.map((f) => f.compiles ?? 0));
    check(compiledInWindow === 0,
        'nothing was compiled on the frames the arrival is made of',
        `peak render.mesh.programCompiles ${compiledInWindow} in the window,`
        + ` ${compiledInRun} across the run`);

    // No SYSTEM timer brackets a hit's publication: `step_` leaves the residency
    // system at `loadAdditive`'s first await. The demand frame's unclaimed wall
    // does — frames[0]; `publishAt` is the flag flipping, a frame later.
    const demandFrame = frames[0];
    const claimedByNoSystem = demandFrame
        ? Math.max(0, demandFrame.ms - sumDomains(demandFrame))
        : 0;
    // Reported beside it, never as it: this is what ran INSIDE the residency
    // system — deciding and starting the load — and it is 0.1 ms against a 7 ms
    // transaction. Witnessing publication with it was witnessing another domain.
    const residencySystem = window.reduce((a, f) => a + (byDomain(f).get('scene') ?? 0), 0)
        - (baselineDomains.get('scene') ?? 0) * window.length;

    for (const [cell, v] of Object.entries(delivery ?? {})) {
        const roots = tree(v.phases);
        const half = (keep) => roots.filter((n) => PREPARATION.has(n.name) === keep);

        console.log(`  ${cell} — where its delivery went\n`);
        console.log('  preparation — between frames, on no system timer, and hideable:');
        printTree(half(true), '    ');
        const prepared = sum(half(true));
        console.log(`    ${'= accounted'.padEnd(22)}${prepared.toFixed(2).padStart(7)} ms`
            + `  of ${v.prepareMs.toFixed(2)} ms issue → prepared   (${pct(prepared, v.prepareMs)})`);

        console.log('\n  publicationCost — the publication transaction: prepared data → ECS-visible.');
        console.log('  What demand pays whatever prefetch did, and it is NOT all of what demand pays:');
        printTree(half(false), '    ');
        const published = sum(half(false));
        // Decided by the STREAMER's verdict, not the arm's name: a hit publishes
        // inside the frame that asked, so wall time there spans the whole frame.
        // Keying it on the arm made a third hitting arm read the wrong clock.
        const witness = v.outcome === 'hit'
            ? { ms: claimedByNoSystem, what: "the demand frame's wall that no system claimed" }
            : { ms: v.publishMs, what: 'publish → resident wall time' };
        console.log(`    ${'= accounted'.padEnd(22)}${published.toFixed(2).padStart(7)} ms`);
        console.log(`    ${'against'.padEnd(22)}${witness.ms.toFixed(2).padStart(7)} ms`
            + `  from ${witness.what} (${pct(published, witness.ms)})`);
        if (v.outcome === 'hit') {
            console.log(`    ${'(publish → resident'.padEnd(22)}${v.publishMs.toFixed(2).padStart(7)} ms`
                + `  wall, which on a hit spans the whole frame — not the transaction.)`);
            console.log(`    ${'(WorldResidencySystem'.padEnd(22)}${residencySystem.toFixed(2).padStart(7)} ms`
                + '  the `scene` domain: what ran inside the system, which is the'
                + ' decision and the start of the load — not the transaction.)');
        }
        console.log(`\n    ${'delivery'.padEnd(22)}${v.deliveryMs.toFixed(2).padStart(7)} ms  issue → resident`);

        // Two instruments on one interval, so either being wrong shows up as
        // disagreement. A one-sided check would pass by over-counting.
        check(published >= witness.ms * 0.9 && published <= witness.ms * 1.15,
            'the publication a player pays for is explained by named work',
            `${published.toFixed(2)} ms of named phases against ${witness.ms.toFixed(2)} ms `
            + `from ${witness.what} (${pct(published, witness.ms)})`);
        // The check above is satisfied by `spawn: 6.8 ms` and nothing else —
        // the state this bench was written to leave. A total is not a mechanism.
        const biggest = leaves(half(false)).sort((a, b) => b.ms - a.ms)[0] ?? { name: 'none', ms: 0 };
        check(biggest.ms <= published * 0.5,
            'and no single undivided phase is most of it — a total would be, a mechanism is not',
            `largest is ${biggest.name} at ${pct(biggest.ms, published)} of publication`);
        const deepest = closure(half(false));
        if (deepest) {
            console.log(`    (the instrument closes to ${(deepest.ratio * 100).toFixed(1)}% at its worst `
                + `parent, ${deepest.name} — reported, not a criterion: sub-phases partition their `
                + `parent by construction.)`);
        }
        check(v.prepareMs - prepared <= RESIDUAL_MS,
            'and so is the preparation prefetch hides',
            `${(v.prepareMs - prepared).toFixed(2)} ms unnamed of ${v.prepareMs.toFixed(2)} ms `
            + `(${pct(prepared, v.prepareMs)})`);
    }

    console.log(`\n  realization — ECS-visible → actually drawn. Steady state ${baseline.toFixed(2)} ms/frame, `
        + `${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 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)}`
            + `${[...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);
    console.log(`    ${'window'.padEnd(7)}${wall.toFixed(2).padStart(7)}${accounted.toFixed(2).padStart(9)}`
        + `${pct(accounted, wall).padStart(10)}`);
    // Every frame costs something outside every system (the step call, the
    // promise turn). Charged to the arrival it makes the ratio a measure of how
    // CHEAP the window was, so excess is judged against excess.
    const wallExcess = wall - baseline * window.length;
    const systemExcess = accounted - baselineSystems * window.length;

    // What the arrival ADDED, which is the only part of these frames residency
    // is answerable for: the same systems run on every other frame too.
    const excess = wallExcess;
    const perDomain = new Map();
    for (const f of window) {
        for (const [domain, ms] of byDomain(f)) perDomain.set(domain, (perDomain.get(domain) ?? 0) + ms);
    }
    for (const [domain, ms] of baselineDomains) {
        perDomain.set(domain, (perDomain.get(domain) ?? 0) - ms * window.length);
    }
    console.log(`\n    the arrival cost these ${window.length} frames ${excess.toFixed(2)} ms above steady state:`);
    for (const [domain, ms] of [...perDomain].sort((a, b) => b[1] - a[1])) {
        if (Math.abs(ms) < 0.05) continue;
        console.log(`      ${domain.padEnd(16)}${ms.toFixed(2).padStart(7)} ms`);
    }

    realization(window, frames[arrivalAt]);

    console.log('');
    // The RESIDUAL, not the ratio: at an excess of 2.7 ms the same 0.2 ms of
    // per-frame overhead reads as 93%, so a ratio would measure how cheap the
    // arrival was. A truncated breakdown still fails this, leaving 3.6 ms.
    const residual = wallExcess - systemExcess;
    if (arrived) {
        check(residual <= RESIDUAL_MS_PER_FRAME * window.length,
            'and what the arrival ADDS to those frames is explained by the systems that ran',
            `${residual.toFixed(2)} ms unnamed of ${wallExcess.toFixed(2)} ms of excess over `
            + `${window.length} frames, against ${(RESIDUAL_MS_PER_FRAME * window.length).toFixed(2)}`
            + ` ms of known per-frame overhead (${pct(systemExcess, wallExcess)})`);
    }

    const first = Object.values(delivery ?? {})[0];
    const publicationCost = first
        ? sum(tree(first.phases).filter((n) => !PREPARATION.has(n.name)))
        : 0;
    const firstVisibleFrameCost = window.length ? Math.max(...window.map((f) => f.ms)) : 0;
    const arrivalWindowCost = excess;
    console.log(`\n  what one heavy arrival costs the main thread:\n`);
    console.log(`    publicationCost        ${publicationCost.toFixed(2).padStart(6)} ms   prepared data → ECS-visible, between frames`);
    console.log(`    firstVisibleFrameCost  ${firstVisibleFrameCost.toFixed(2).padStart(6)} ms   the dearest single frame of the arrival`);
    console.log(`    arrivalWindowCost      ${arrivalWindowCost.toFixed(2).padStart(6)} ms   ${window.length} frames, above steady state`);
    console.log(`    ${'─'.repeat(60)}`);
    console.log(`    ECS publication finishing is not the delivery paid for: the larger`);
    console.log(`    half lands after it, in realization.\n`);

    // A budget line, not a tolerance: an arrival may have half a 60 Hz frame
    // because the GAME needs the other half. This fixture's world is nearly
    // empty, so a pass says nothing about a real one and a fail says everything.
    const HEADROOM = 1000 / 60 / 2;
    const spike = firstVisibleFrameCost - baseline;
    const fits = spike <= HEADROOM;
    console.log('');
    // Through `check`: this verdict was incrementing a tally the exit code does
    // not read, so a run that printed the violation still exited 0.
    check(fits, 'BUDGET — a heavy arrival leaves the game its half of the frame',
          `${spike.toFixed(2)} ms of arrival work against ${HEADROOM.toFixed(2)} ms of headroom`);

    void failed;  // every verdict goes through `check`
    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:');
        const calm = frames.slice(-60).find((f) => f.upload && f.upload[1] > 0);
        if (calm) {
            console.log(`      steady   ${calm.ms.toFixed(2).padStart(7)} ms`
                + `  upload  streams ${calm.upload[0]}  vtx ${calm.upload[1]}B`
                + `  idx ${calm.upload[2]}B  grows ${calm.upload[3]}  writes ${calm.upload[4]}`);
        }
        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)'}`);
            // Beside the cost, what the upload was asked to move on that very
            // frame — and what a quiet frame was asked to move, so "the same
            // bytes cost ten times as much" is readable rather than inferred.
            const u = f.upload;
            if (u) {
                console.log(`          upload  streams ${u[0]}  vtx ${u[1]}B  idx ${u[2]}B`
                    + `  grows ${u[3]}  writes ${u[4]}`);
            }
            // 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`
        + ` — ${[...byDomain(worst)].sort((a, b) => b[1] - a[1]).filter(([, ms]) => ms >= 0.05).slice(0, 4)
            .map(([d, ms]) => `${d} ${ms.toFixed(2)}`).join(', ') || 'no breakdown'}`
        + `${worstAt >= arrivalAt && worstAt < arrivalAt + window.length ? '  (inside the arrival window)'
            : '  (OUTSIDE the arrival window)'}`);
}

/**
 * A cell's phases, as the tree their dotted names describe.
 *
 * `spawn.components.MeshRenderer` is inside `spawn.components` is inside
 * `spawn`, so the roots are the only rows that may be summed — adding the whole
 * flat list counts the same milliseconds three times.
 */
function tree(phases) {
    const nodes = new Map();
    const node = (name) => {
        let n = nodes.get(name);
        if (!n) { n = { name, ms: 0, children: [] }; nodes.set(name, n); }
        return n;
    };
    for (const [name, ms] of Object.entries(phases)) node(name).ms = ms;
    const roots = [];
    for (const [name, n] of nodes) {
        const cut = name.lastIndexOf('.');
        if (cut < 0) roots.push(n);
        else node(name.slice(0, cut)).children.push(n);
    }
    const order = (list) => {
        list.sort((a, b) => b.ms - a.ms);
        for (const n of list) order(n.children);
    };
    order(roots);
    return roots;
}

const sum = (nodes) => nodes.reduce((total, n) => total + n.ms, 0);

/** Every phase with no breakdown of its own — the rows a total could hide in. */
function leaves(nodes) {
    const out = [];
    const walk = (list) => {
        for (const n of list) {
            if (n.children.length === 0) out.push(n);
            else walk(n.children);
        }
    };
    walk(nodes);
    return out;
}

/**
 * The worst parent at explaining itself. Summing the ROOTS is blind to a `spawn`
 * measured as one number: its root sum is perfect and it explains nothing.
 */
function closure(nodes) {
    let worst = null;
    const walk = (list) => {
        for (const n of list) {
            if (n.children.length > 0 && n.ms > 0.05) {
                const ratio = sum(n.children) / n.ms;
                if (worst === null || ratio < worst.ratio) worst = { name: n.name, ratio, ms: n.ms };
            }
            walk(n.children);
        }
    };
    walk(nodes);
    return worst;
}


/** Print one phase subtree, naming what its children do not explain. */
function printTree(nodes, indent) {
    for (const n of nodes) {
        const leaf = n.name.slice(n.name.lastIndexOf('.') + 1);
        console.log(`${indent}${leaf.padEnd(26 - indent.length)}${n.ms.toFixed(2).padStart(7)} ms`);
        if (n.children.length === 0) continue;
        printTree(n.children, indent + '  ');
        // A parent measured by one clock against children measured by another:
        // the gap is real work nobody named, and hiding it would make every
        // accounting below true by construction.
        const rest = n.ms - sum(n.children);
        if (rest > 0.005) {
            console.log(`${indent}  ${'(unattributed)'.padEnd(24 - indent.length)}${rest.toFixed(2).padStart(7)} ms`);
        }
    }
}

/** Which half of delivery owns a root phase — the split prefetch turns on. */
const PREPARATION = new Set(['fetch', 'prefab', 'assets', 'discover', 'subsystems', 'readying']);


const pct = (part, whole) => (whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : '—');
const median = (values) => {
    if (values.length === 0) return NaN;
    const sorted = [...values].sort((a, b) => a - b);
    return sorted[Math.floor(sorted.length / 2)];
};

/**
 * Inside the render domain, on the frame the arrival landed on.
 *
 * Systems say WHICH subsystem paid; only the scopes say what it was doing. The
 * `cpp.*` rows nest inside the JS scope that called them, so the two are printed
 * as lists and never summed into one total.
 */
function realization(window, arrival) {
    const rows = [];
    for (const f of window) {
        for (const s of f.scopes ?? []) rows.push({ where: 'js', ...s, frame: f });
        for (const [name, ms] of Object.entries(f.native ?? {})) {
            rows.push({ where: 'cpp', name, ms, system: '', frame: f });
        }
    }
    if (rows.length === 0) {
        console.log('\n    (no scopes: the frames were too cheap to carry a breakdown)');
        return;
    }
    console.log('\n    inside the arrival frames, by scope:');
    const total = new Map();
    for (const r of rows) {
        const key = `${r.where}  ${r.name}`;
        total.set(key, (total.get(key) ?? 0) + r.ms);
    }
    for (const [name, ms] of [...total].sort((a, b) => b[1] - a[1])) {
        if (ms < 0.05) continue;
        console.log(`      ${name.padEnd(30)}${ms.toFixed(2).padStart(7)} ms`);
    }
    // Divisors, so a phase that GREW and one whose unit cost grew are told
    // apart: the same milliseconds over ten items and over a thousand are two
    // different findings.
    const counts = Object.entries(arrival?.counters ?? {})
        .filter(([k]) => k.startsWith('render.mesh.') || k === 'render.meshes');
    if (counts.length > 0) {
        console.log('\n    what it walked on that frame:');
        for (const [k, v] of counts) console.log(`      ${k.padEnd(30)}${String(v).padStart(7)}`);
    }
    const renderSystem = (arrival?.costs ?? []).find((c) => c.name === 'RenderSystem');
    if (renderSystem) {
        const js = rows.filter((r) => r.where === 'js' && r.system === 'RenderSystem'
            && r.frame === arrival).reduce((a, r) => a + r.ms, 0);
        console.log(`\n      RenderSystem on the arrival frame ${renderSystem.ms.toFixed(2)} ms,`
            + ` of which ${js.toFixed(2)} ms is named by JS scopes`
            + ` (${((js / renderSystem.ms) * 100).toFixed(0)}%)`);
    }
}

const KEY_WORDS = ['keysLo', 'keysHi', 'keysLo2', 'keysHi2'];
/** The variant keys a prewarm derived, as a set a reader can compare by eye. A
 *  bit per mesh variant, over as many words as the engine's variant space needs:
 *  reading only the first two would call two answers equal on the strength of
 *  the half of them that happens to be read. */
function keySet(r) {
    const keys = [];
    KEY_WORDS.forEach((word, w) => {
        for (let i = 0; i < 32; i++) if (r[word] & (1 << i)) keys.push(w * 32 + i);
    });
    return keys;
}
/** Whether two prewarms need the same set — every word, for the reason above. */
const sameKeys = (a, b) => KEY_WORDS.every((word) => a[word] === b[word]);
/** Rendered for a log line. */
const keySetText = (r) => `{${keySet(r).join(', ')}}`;

/** What one frame cost, by the domain that owns each system. */
function byDomain(frame) {
    return new Map(Object.entries(frame.domains ?? {}));
}

/** What this frame's systems cost in total — the attributed half of its wall time. */
function sumDomains(frame) {
    let total = 0;
    for (const ms of Object.values(frame.domains ?? {})) total += ms;
    return total;
}

main();