A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file One arm at one workload point, printing one JSON object.
*
* node bench/replication-interest/arm.mjs --arm A --entities 100000 --connections 32
*/
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
loadSdk, connectEngine, buildWorld, applyMovement, newStats,
visibleForA, visibleForB, visibleForC0, visibleForC1,
buildPositionCache, buildGrid, diffAndFilter,
newLiveGrid, seedLiveGrid, updateLiveGrid, gridDrift,
} from './workload.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
const argv = process.argv.slice(2);
const flag = (name, fallback) => {
const i = argv.indexOf(`--${name}`);
return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : fallback;
};
const ARM = flag('arm', 'A');
const ENTITIES = Number(flag('entities', '100000'));
const CONNECTIONS = Number(flag('connections', '32'));
const ANCHORS = Number(flag('anchors', '1'));
/** Fraction of the population a connection should see; radius is solved for it. */
const VISIBLE = Number(flag('visible', '0.01'));
const MOVEMENT = Number(flag('movement', '0.01'));
const SIM_HZ = Number(flag('simHz', '60'));
const REPL_HZ = Number(flag('replHz', '20'));
const WARMUP = Number(flag('warmup', '60'));
const MEASURE = Number(flag('measure', '240'));
/** Compare this arm's visible set against arm A's, every connection, every sample. */
const VERIFY = argv.includes('--verify');
const REPL_EVERY = Math.round(SIM_HZ / REPL_HZ);
const sdk = await loadSdk(ROOT);
const app = sdk.App.new();
const engine = await connectEngine(sdk, app, ROOT);
const world = app.world;
const ctx = buildWorld(sdk, world, {
population: ENTITIES, connections: CONNECTIONS, anchorsPerConn: ANCHORS,
});
// The grid is `side × side` at one unit per cell, so a disc of radius r covers
// πr² cells: solve that for the requested fraction of the population.
const RADIUS = VISIBLE >= 1
? ctx.side * 2
: Math.sqrt((VISIBLE * ENTITIES) / Math.PI);
const R2 = RADIUS * RADIUS;
const MOVE_COUNT = Math.round(ENTITIES * MOVEMENT);
// The composed world transforms exist because something asked, not because a
// frame happened. A server asks here, before it samples.
world.ensureTransformsComposed();
// The measured path is the composed one, not a local-space lookalike: a child of
// a parent at 100, five to its right, has to read 105.
{
const p = world.spawn();
world.insert(p, ctx.Pos, { position: { x: 100, y: 0, z: 0 } });
const c = world.spawn();
world.insert(c, ctx.Pos, { position: { x: 5, y: 0, z: 0 } });
world.setParent(c, p);
world.ensureTransformsComposed();
const composed = world.tryGet(c, ctx.Pos)?.worldPosition?.x;
if (composed !== 105) {
process.stderr.write(`sentinel: composed child x = ${composed}, want 105\n`);
process.exit(1);
}
world.despawn(c);
world.despawn(p);
}
// The ids come back as an address into the engine's own memory — a JS array of a
// hundred thousand handles would cost more than the walk that found them. The
// view is rebuilt each call: growing the heap detaches the old one.
const cppRegistry = world.getCppRegistry();
const EMPTY = new Uint32Array(0);
function composeCollecting() {
engine.transform_setChangeTracking(true);
world.ensureTransformsComposed();
const r = engine.transform_compositionChanges();
const ids = r.count === 0 ? EMPTY : new Uint32Array(engine.HEAPU32.buffer, r.ptr, r.count);
// Copied before acknowledging: the view is over the engine's own vector.
const out = ids.length === 0 ? EMPTY : Uint32Array.from(ids);
engine.transform_takeChanges();
return out;
}
// Arm P is the SHIPPED provider, driven the way the server drives it — the arms
// above are this bench's own reproduction of the path, and a number that
// describes a copy is a number about the copy.
const shipped = ARM === 'P' ? sdk.radiusInterestProvider(RADIUS) : null;
let shippedPrepared = null;
let shippedSeeded = false;
// Its position reads happen inside the SDK, so they are counted where the
// canonical reader takes them rather than where this file would.
let counting = false;
if (shipped) {
const original = world.tryGet.bind(world);
world.tryGet = (e, c) => {
if (counting && c === ctx.Pos) stats.visited.positionReads++;
return original(e, c);
};
}
const liveGrid = ARM === 'D1' ? newLiveGrid(RADIUS) : null;
let seedUs = 0;
if (liveGrid) {
const seedStats = newStats();
seedLiveGrid(world, ctx, seedStats, liveGrid);
seedUs = Number(seedStats.ns.build) / 1000;
}
const stats = newStats();
const previous = new Map();
for (let c = 0; c < CONNECTIONS; c++) previous.set(c, new Set());
const oracle = VERIFY ? new Map() : null;
if (oracle) for (let c = 0; c < CONNECTIONS; c++) oracle.set(c, new Set());
let mismatches = 0;
let samples = 0;
let totalNs = 0n;
let movedTotal = 0;
function sampleOnce(measuring) {
const t0 = process.hrtime.bigint();
// What a server does before an interest snapshot. With no transform mutation
// since the last one this is the epoch comparison and nothing else.
const et = process.hrtime.bigint();
const changed = ARM === 'D1' ? composeCollecting() : (world.ensureTransformsComposed(), null);
if (measuring) stats.ns.ensure += process.hrtime.bigint() - et;
const mt = process.hrtime.bigint();
const candidates = [...ctx.entities];
if (measuring) {
stats.ns.materialize += process.hrtime.bigint() - mt;
stats.visited.candidates += candidates.length;
}
// A sample's worth of dirty/removal rows, sized like a sparse world.
const dirty = candidates.slice(0, Math.max(1, Math.round(ENTITIES * 0.01)));
const removals = [];
// Built once per sample, which is what makes an arbitrary position function
// safe here: nothing is carried between samples to go stale.
const shared = measuring ? stats : newStats();
const cache = ARM === 'C0' ? buildPositionCache(world, ctx, shared) : null;
const grid = ARM === 'C1' ? buildGrid(world, ctx, shared, RADIUS)
: ARM === 'D1' ? (updateLiveGrid(world, ctx, shared, liveGrid, changed), liveGrid) : null;
if (shipped) {
const t = process.hrtime.bigint();
shippedPrepared = shipped.prepare({
world, entities: ctx.entities, entityCount: ctx.entities.length,
// The server's membership feed: everything enters once, and this
// workload spawns and despawns nothing after that.
entered: shippedSeeded ? [] : ctx.entities, left: [], rechecked: [],
});
shippedSeeded = true;
if (measuring) shared.ns.build += process.hrtime.bigint() - t;
}
for (let c = 0; c < CONNECTIONS; c++) {
const use = measuring ? stats : newStats();
if (shipped) {
const owned = ctx.owned.get(c) ?? [];
const t = process.hrtime.bigint();
const answer = shippedPrepared.query({ connectionId: c, owned });
const visible = answer === 'all' ? new Set(candidates) : new Set(answer);
// The server's own invariant, applied where the server applies it.
for (const e of owned) visible.add(e);
if (measuring) use.ns.radius += process.hrtime.bigint() - t;
if (VERIFY) {
const truth = visibleForA(world, ctx, c, candidates, R2, newStats());
if (truth.size !== visible.size) mismatches++;
else for (const e of truth) if (!visible.has(e)) { mismatches++; break; }
}
diffAndFilter(visible, previous.get(c), dirty, removals, use);
previous.set(c, visible);
continue;
}
const visible = ARM === 'C1' || ARM === 'D1'
? visibleForC1(ctx, c, candidates, R2, use, ctx.owned, grid, RADIUS)
: ARM === 'C0'
? visibleForC0(ctx, c, candidates, R2, use, ctx.owned, cache)
: ARM === 'B'
? visibleForB(world, ctx, c, candidates, R2, use, ctx.owned)
: visibleForA(world, ctx, c, candidates, R2, use, ctx.owned);
if (VERIFY) {
// Set equality, not size: an arm that both misses one entity and
// invents another has the same count and a different answer.
const truth = visibleForA(world, ctx, c, candidates, R2, newStats());
if (truth.size !== visible.size) mismatches++;
else {
for (const e of truth) if (!visible.has(e)) { mismatches++; break; }
for (const e of visible) if (!truth.has(e)) { mismatches++; break; }
}
}
diffAndFilter(visible, previous.get(c), dirty, removals, use);
previous.set(c, visible);
}
if (measuring) {
totalNs += process.hrtime.bigint() - t0;
samples++;
}
}
function run(count, measuring) {
counting = measuring;
for (let t = 0; t < count; t++) {
const tick = measuring ? WARMUP + t : t;
movedTotal += applyMovement(world, ctx, tick, MOVE_COUNT);
world.advanceTick();
if ((tick + 1) % REPL_EVERY !== 0) continue;
sampleOnce(measuring);
}
}
run(WARMUP, false);
run(MEASURE, true);
// The invariant a KEPT structure lives or dies by. The per-sample visible-set
// check does not reach it: a stale cell shows up there only if it changes
// somebody's view, and at 1% visible most of the world is nobody's.
const drift = liveGrid ? gridDrift(liveGrid, buildGrid(world, ctx, newStats(), RADIUS)) : null;
const simSeconds = MEASURE / SIM_HZ;
const us = (ns) => Number(ns) / 1000;
const per = (v) => v / simSeconds;
process.stdout.write(`${JSON.stringify({
arm: ARM, entities: ENTITIES, connections: CONNECTIONS, anchors: ANCHORS,
visible: VISIBLE, movement: MOVEMENT, radius: RADIUS, verify: VERIFY,
simSeconds, samples, mismatches, movedTotal, seedUs, drift,
totalUsPerSimSecond: per(us(totalNs)),
segmentUsPerSimSecond: Object.fromEntries(
Object.entries(stats.ns).map(([k, v]) => [k, per(us(v))]),
),
visitedPerSample: Object.fromEntries(
Object.entries(stats.visited).map(([k, v]) => [k, samples > 0 ? v / samples : 0]),
),
visiblePerConnection: samples > 0 ? stats.visibleTotal / (samples * CONNECTIONS) : 0,
})}\n`);