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.

21.7 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  bench/residency/prefetch.mjs — did the place get ready before it was wanted?
 *
 * The heavy-cell profile settled what an arrival COSTS and found nothing worth a
 * budget scheduler. That moved the question: what delivery claims now is not
 * that publication got cheaper but that fetching and decoding happen before the
 * player needs the place. So the number that decides whether it works is not a
 * duration at all — it is how often demand finds readiness already there.
 *
 * Two runs over the same corridor of identical cells, cold each time:
 *
 *   approach   a source walks in, so speculation has the lead time it was
 *              designed for           → demand should find the cell PREPARED
 *   teleport   a source appears in a cell it was never near
 *                                     → demand finds nothing, and pays the
 *                                       preparation itself
 *
 * and a third that is this bench's own falsifier: the same walk with prefetch
 * turned down to the load radius. If the approach row does not collapse into the
 * teleport row, the approach row was never measuring prefetch.
 *
 *   node bench/residency/prefetch.mjs
 *   node bench/residency/prefetch.mjs --props 60 --bodies 240   heavier cells
 */
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-prefetch');
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 COLUMNS = 16;
const PROPS = Number(flag('props', '40'));
const BODIES = Number(flag('bodies', '160'));

/**
 * The radii every scenario runs at.
 *
 * `unload` is deliberately NOT below `prefetch`: a cell given up while still
 * inside the prefetch radius is speculated about again the moment it goes, and
 * the walk would be measuring its own churn.
 */
const LOAD = 200;
const PREFETCH = 1200;
const UNLOAD = 1300;
const SPEED = 600;

/** Where a teleporting source lands: cell centres far enough apart that the next
 *  one was never inside the prefetch radius of the last. */
const STOPS = [0, 3, 6, 9, 12, 15].map((c) => c * CELL + CELL / 2);

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: a cell's preparation is only worth
    // hiding if it is decoding real meshes and materials.
    cpSync(SAMPLE, path.join(dir, 'assets', 'models'), { recursive: true });

    const entities = [];
    const transform = (x, y, z, s = 1) => ({
        type: 'Transform',
        data: { position: { x, y, z }, scale: { x: s, y: s, z: s } },
    });
    const solid = (h) => ([
        { type: 'RigidBody3D', data: { bodyType: 0 } },
        { type: 'BoxCollider3D', data: { halfExtents: { x: h, y: h, z: h }, friction: 0.6 } },
    ]);
    const push = (id, name, components, parent = null) =>
        entities.push({ id, name, parent, children: [], visible: true, components });

    push(0, 'World', [transform(0, 0, 0),
        { type: 'StreamedWorld', data: { cellSize: CELL } }]);
    push(1, 'Camera', [transform(0, 1200, 1800),
        { type: 'Camera', data: { projectionType: 0, fov: 55, nearPlane: 10, farPlane: 20000,
                                   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: {} }]);
    // Parked a whole prefetch radius short of the first cell, so the run begins
    // with nothing speculated about and the first arrival is a real one.
    push(3, 'Source', [transform(-(PREFETCH + 200), 60, CELL / 2),
        { type: 'WorldStreamingSource',
          data: { prefetchRadius: 0, loadRadius: 0, unloadRadius: 0, enabled: false } },
        { type: 'WorldPersistent', data: {} }]);

    const LEVELS = ['rock-lod0', 'rock-lod1', 'rock-lod2'];
    let id = 100;
    for (let cx = 0; cx < COLUMNS; cx++) {
        // Identical cell to cell, so "the same content arrived" is a fact about
        // the fixture and not a hope about the cook.
        for (let n = 0; n < PROPS; n++) {
            push(id++, `Rock_${cx}_${n}`, [
                transform(cx * CELL + 20 + (n % 8) * 22, 30, 20 + Math.floor(n / 8) * 22, 1),
                { type: 'MeshRenderer', data: { mesh: `assets/models/${LEVELS[n % 3]}.esmesh`,
                    lit: true, opaque: true, color: { r: 0.5, 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++) {
            push(id++, `Body_${cx}_${n}`, [
                transform(cx * CELL + 10 + (n % 20) * 9, 30, 300 + Math.floor(n / 20) * 9, 0.2),
                { type: 'MeshRenderer', data: { mesh: 'builtin:cube', lit: true, opaque: true,
                    cullBackfaces: true, color: { r: 0.6, g: 0.55, b: 0.45, a: 1 } } },
                ...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: 'Prefetch Bench', description: 'A corridor of identical cells.',
        tag: '3D', version: '0.1.0', defaultScene: 'assets/scenes/main.esscene',
        designResolution: { width: 640, height: 360 }, spineVersion: 'none',
    }, null, 2) + '\n');
    // The source moves itself, at a fixed step, because the driver may not: a
    // harness that placed the source would be choosing when demand arrives, and
    // that is the entire quantity under measurement.
    writeFileSync(path.join(dir, 'src', 'main.ts'), `
import { addSystemToSchedule, Schedule, defineSystem, GetWorld, Res, Input, Transform, WorldStreamingSource } from 'esengine';
import type { World, InputState } from 'esengine';

const STEP = ${SPEED} / 60;
const STOPS = ${JSON.stringify(STOPS)};
const DWELL = 90;

let mode: '' | 'walk' | 'teleport' = '';
let ran = 0;

const driveSystem = defineSystem(
    [Res(Input), GetWorld()],
    (input: InputState, world: World) => {
        const source = world.findEntityByName('Source');
        if (source === null) return;
        const begin = (next: 'walk' | 'teleport', prefetch: number) => {
            if (mode !== '') return;
            mode = next;
            ran = 0;
            world.update(source, WorldStreamingSource, (s) => {
                s.prefetchRadius = prefetch;
                s.loadRadius = ${LOAD};
                s.unloadRadius = ${UNLOAD};
                s.enabled = true;
            });
        };
        if (input.isKeyPressed('Digit1')) begin('walk', ${PREFETCH});
        if (input.isKeyPressed('Digit2')) begin('teleport', ${PREFETCH});
        // Speculation reaching no further than demand: the same walk with
        // nothing able to run ahead of it.
        if (input.isKeyPressed('Digit3')) begin('walk', ${LOAD});
        if (mode === 'walk') {
            world.update(source, Transform, (t) => { t.position.x += STEP; });
        } else if (mode === 'teleport') {
            const stop = STOPS[Math.min(Math.floor(ran / DWELL), STOPS.length - 1)];
            world.update(source, Transform, (t) => { t.position.x = stop; });
        }
        if (mode !== '') ran++;
    },
    { name: 'PrefetchDriveSystem' },
);
addSystemToSchedule(Schedule.Update, driveSystem);
`);
    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;
}

/** Frames enough to walk the corridor's first seven cells, and to make every stop. */
const WALK_FRAMES = Math.ceil(((COLUMNS / 2) * CELL + PREFETCH + 200) / SPEED * 60);
const STOP_FRAMES = STOPS.length * 90 + 60;

function drive(dir, name, steps) {
    const script = path.join(WORK, `${name}.json`);
    writeFileSync(script, JSON.stringify(steps, null, 2));
    // A fresh Electron per scenario: the launcher clears the HTTP cache at boot,
    // so each run pays for its own fetching. Two scenarios in one process would
    // hand the second a warmed cache and call the difference prefetch.
    const run = runElectron([LAUNCHER, '--dir', dir, '--script', script, '--w', '640', '--h', '360'],
        { encoding: 'utf8', cwd: ROOT });
    for (const line of (run.stdout || '').split('\n')) {
        const at = line.indexOf('stream ');
        if (at < 0) continue;
        try { return JSON.parse(line.slice(line.indexOf('{', at))); } catch { /* partial line */ }
    }
    console.error(`✗ ${name}: nothing was measured — ${(run.stdout || run.stderr || '').slice(-600)}`);
    process.exit(2);
}

const percentile = (values, p) => {
    if (values.length === 0) return NaN;
    const sorted = [...values].sort((a, b) => a - b);
    return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
};
const ms = (v) => (Number.isNaN(v) ? '—' : `${v.toFixed(1)}`);

/** The arrivals a scenario produced, one row per cell that was actually asked for. */
function arrivals(streaming) {
    const rows = [];
    for (const [cell, d] of Object.entries(streaming.delivery ?? {})) {
        if (d.outcome === '' || d.demandToResidentMs <= 0) continue;
        rows.push({
            cell,
            outcome: d.outcome,
            latency: d.demandToResidentMs,
            prepare: d.prepareMs,
            publish: d.publishMs,
            dwell: d.dwellMs,
            fetch: d.phases?.fetch ?? 0,
            assets: d.phases?.assets ?? 0,
            spawn: d.phases?.spawn ?? 0,
        });
    }
    // In corridor order, so the first (cold) arrival is visibly the first.
    return rows.sort((a, b) => Number(a.cell.match(/\d+/g).at(-2)) - Number(b.cell.match(/\d+/g).at(-2)));
}

/**
 * What a cell that is READY but not published can be seen to own.
 *
 * Asked of the world's own totals, not of the streamer's report of itself: an
 * entity belonging to no resident cell is one a preparation leaked, whatever
 * the streamer says about it.
 */
function unpublished(streaming) {
    const prepared = streaming.preparedCells ?? [];
    const entityRows = streaming.cellEntityCounts ?? {};
    const renderRows = streaming.cellRenderCounts ?? {};
    const inCells = Object.values(entityRows).reduce((a, b) => a + b, 0);
    return {
        prepared,
        resident: streaming.residentCells.length,
        entities: streaming.entities,
        persistent: streaming.persistentEntities,
        inCells,
        bodies: streaming.physicsBodies,
        named: prepared.filter((c) => c in entityRows || c in renderRows),
        // Persistent world + every resident cell should be the whole population.
        unowned: streaming.entities - streaming.persistentEntities - inCells,
        // The fixture puts bodies in cells and none in the persistent world, so
        // the solver's population is a count of published cells and nothing else.
        strayBodies: streaming.physicsBodies - streaming.residentCells.length * BODIES,
        stalePhysics: streaming.stalePhysics ?? 0,
    };
}

function summarise(streaming) {
    const rows = arrivals(streaming);
    const latency = rows.map((r) => r.latency);
    const hits = rows.filter((r) => r.outcome === 'hit');
    const asked = streaming.prefetchHits + streaming.prefetchMisses;
    return {
        rows,
        requested: streaming.prefetchRequests,
        stillReady: streaming.preparedCells.length,
        hits: streaming.prefetchHits,
        misses: streaming.prefetchMisses,
        cancelled: streaming.cancelCount,
        hitRate: asked === 0 ? NaN : streaming.prefetchHits / asked,
        latency50: percentile(latency, 0.5),
        latency95: percentile(latency, 0.95),
        dwell50: percentile(hits.map((r) => r.dwell), 0.5),
        dwell95: percentile(hits.map((r) => r.dwell), 0.95),
        prepare: percentile(rows.map((r) => r.prepare), 0.5),
        publish: percentile(rows.map((r) => r.publish), 0.5),
        fetch: percentile(rows.map((r) => r.fetch), 0.5),
        assets: percentile(rows.map((r) => r.assets), 0.5),
        spawn: percentile(rows.map((r) => r.spawn), 0.5),
        unpublished: unpublished(streaming),
    };
}

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 corridor did not package:\n${(built.stderr || built.stdout || '').slice(-900)}`);
        process.exit(2);
    }

    const scenarios = [
        ['approach', { do: 'stream', as: 'approach', key: 'Digit1', count: WALK_FRAMES }],
        ['teleport', { do: 'stream', as: 'teleport', key: 'Digit2', count: STOP_FRAMES }],
        ['no-prefetch', { do: 'stream', as: 'noPrefetch', key: 'Digit3', count: WALK_FRAMES }],
    ];
    const measured = new Map();
    for (const [name, step] of scenarios) {
        measured.set(name, summarise(drive(out, name, [{ do: 'step', frames: 30 }, step])));
    }

    console.log(`\nprefetch effectiveness — ${COLUMNS} identical cells, `
        + `${PROPS} imported props + ${BODIES} bodies each, cell ${CELL} wu`);
    console.log(`  load ${LOAD} / prefetch ${PREFETCH} / unload ${UNLOAD} wu, walking ${SPEED} wu/s\n`);

    console.log('  scenario       requested  hits  misses  cancelled  still ready  hit rate');
    for (const [name, s] of measured) {
        console.log(`  ${name.padEnd(13)}  ${String(s.requested).padStart(9)}`
            + `  ${String(s.hits).padStart(4)}  ${String(s.misses).padStart(6)}`
            + `  ${String(s.cancelled).padStart(9)}  ${String(s.stillReady).padStart(11)}`
            + `  ${(Number.isNaN(s.hitRate) ? '—' : `${(s.hitRate * 100).toFixed(0)}%`).padStart(8)}`);
    }
    console.log('  (a speculation is requested once, then hit, cancelled, or still waiting.)');

    console.log(`\n  what the player waits through, milliseconds`
        + ` (dwell is wall time; the designed lead is`
        + ` ${((PREFETCH - LOAD) / SPEED).toFixed(2)} s of walking):`);
    console.log('  scenario       arrivals  loadRadius→resident      prepared dwell     preparation  publication');
    console.log('                             p50     p95            p50      p95      (median)     (median)');
    for (const [name, s] of measured) {
        console.log(`  ${name.padEnd(13)}  ${String(s.rows.length).padStart(8)}`
            + `  ${ms(s.latency50).padStart(9)} ${ms(s.latency95).padStart(7)}`
            + `      ${ms(s.dwell50).padStart(9)} ${ms(s.dwell95).padStart(7)}`
            + `  ${ms(s.prepare).padStart(11)}  ${ms(s.publish).padStart(11)}`);
    }

    console.log('\n  and where a preparation goes (median): '
        + [...measured].map(([name, s]) =>
            `${name} fetch ${ms(s.fetch)} + assets ${ms(s.assets)} → spawn ${ms(s.spawn)}`).join('\n'
            + '                                         '));

    console.log('\n  every arrival, in corridor order:');
    for (const [name, s] of measured) {
        console.log(`    ${name}`);
        for (const r of s.rows) {
            console.log(`      ${r.cell.padEnd(12)} ${r.outcome.padEnd(5)}`
                + ` demand→resident ${ms(r.latency).padStart(6)}`
                + `  prepare ${ms(r.prepare).padStart(6)}  publish ${ms(r.publish).padStart(6)}`
                + `  dwell ${ms(r.dwell).padStart(7)}`);
        }
    }

    // The corridor's cells share their rock meshes, so only the first one of a
    // cold run pays a real `assets` phase — which makes this row the one place
    // a whole preparation is on show.
    const cold = (name) => measured.get(name).rows.find((r) => r.cell.endsWith('cell_0_0'));
    console.log('\n  the one cold cell each run pays for — same content, same fetch, same assets:');
    for (const name of ['approach', 'teleport', 'no-prefetch']) {
        const r = cold(name);
        if (!r) continue;
        console.log(`    ${name.padEnd(13)} preparation ${ms(r.prepare).padStart(6)} ms`
            + ` ${r.outcome === 'hit' ? 'hidden behind a dwell of ' + ms(r.dwell) + ' ms' : 'paid at the door'}`
            + ` → the player waited ${ms(r.latency)} ms`);
    }

    console.log('\n  what a readied-but-unpublished cell owns, when the walk ends:');
    console.log('  scenario       prepared  resident  entities  persistent   in cells  unowned'
        + '   bodies  stray');
    for (const [name, s] of measured) {
        const u = s.unpublished;
        console.log(`  ${name.padEnd(13)}  ${String(u.prepared.length).padStart(8)}`
            + `  ${String(u.resident).padStart(8)}  ${String(u.entities).padStart(8)}`
            + `  ${String(u.persistent).padStart(10)}  ${String(u.inCells).padStart(9)}`
            + `  ${String(u.unowned).padStart(7)}  ${String(u.bodies).padStart(7)}`
            + `  ${String(u.strayBodies).padStart(5)}`);
    }
    console.log('  (entities must be persistent + in cells exactly; a preparation that spawned'
        + '\n   anything would be in the total and in no cell.)');

    const approach = measured.get('approach');
    const teleport = measured.get('teleport');
    const sabotage = measured.get('no-prefetch');
    const checks = [
        [approach.hits > 0 && approach.hitRate >= 0.8,
            'walking in finds the place already prepared',
            `${approach.hits}/${approach.hits + approach.misses} arrivals hit`],
        [teleport.misses > 0 && teleport.hits === 0,
            'appearing in a place nobody was near finds nothing ready',
            `${teleport.misses} miss(es), ${teleport.hits} hit(s)`],
        [approach.latency50 < teleport.latency50,
            'and a hit is the shorter wait of the two',
            `${ms(approach.latency50)} ms vs ${ms(teleport.latency50)} ms at p50`],
        [approach.latency50 <= approach.publish * 1.6 + 1,
            'a hit costs about what publishing costs, and no preparation',
            `${ms(approach.latency50)} ms against ${ms(approach.publish)} ms of publication`],
        // Not `latency50 >= prepare50 + publish50`: medians of three
        // distributions have no reason to add up, and that form passed by luck
        // and then failed by 0.02 ms.
        [teleport.latency50 >= teleport.publish * 1.6,
            'a miss waits for much more than publishing',
            `${ms(teleport.latency50)} ms against ${ms(teleport.publish)} ms of publication`],
        [teleport.rows.every((r) => r.latency >= r.publish),
            'and every miss contains its own publication',
            `${teleport.rows.filter((r) => r.latency < r.publish).length} of `
            + `${teleport.rows.length} arrival(s) shorter than the publication inside them`],
        [sabotage.hits === 0,
            'and with speculation reaching no further than demand, the same walk hits nothing',
            `${sabotage.hits} hit(s), ${sabotage.misses} miss(es)`],
        // Vacuously true where nothing is prepared, so the arm that has to
        // answer it is named: a run that readied nothing has not been asked.
        [approach.unpublished.prepared.length > 0,
            'the walk ends with readiness still unclaimed, so there is something to be invisible',
            `${approach.unpublished.prepared.length} cell(s) prepared and unpublished`],
        [approach.unpublished.named.length === 0
            && approach.unpublished.unowned === 0
            && approach.unpublished.strayBodies === 0
            && approach.unpublished.stalePhysics === 0,
            'and nothing it readied is in the world, the renderer or the solver',
            `${approach.unpublished.named.length} cell row(s), ${approach.unpublished.unowned} `
            + `unowned entit(ies), ${approach.unpublished.strayBodies} stray bod(ies)`],
    ];
    console.log('');
    let failed = 0;
    for (const [ok, claim, detail] of checks) {
        if (!ok) failed++;
        console.log(`  ${ok ? '✓' : '✗'} ${claim}${detail ? ` — ${detail}` : ''}`);
    }
    console.log('');
    process.exit(failed === 0 ? 0 : 1);
}

main();