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.

8.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  The one workload every arm runs, and the four ways of finding what
 *        changed. Shared so the arms differ in EXACTLY the mechanism under
 *        test: the same entities, the same components, the same fields, the
 *        same values, on the same ticks.
 *
 * The mutation schedule is a pure function of (tick, entityCount, dirtyRate) —
 * no RNG state, so two processes cannot drift apart. Selection strides by a
 * prime rather than taking a contiguous run, so a scan cannot be flattered by
 * locality the real thing would not have.
 */
import { pathToFileURL } from 'node:url';
import { createHash } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { readdirSync, readFileSync, statSync } from 'node:fs';
import path from 'node:path';

export { loadSdk, sdkIdentity } from '../lib/sdkBuild.mjs';

const STRIDE = 7919; // coprime with every entity count used here


/**
 * Four replicated components per entity, of which THREE are mutated and one is
 * static — a scan pays for every replicated component whether it moves or not,
 * and a world where everything moves is not the world being modelled.
 */
export function defineWorkloadComponents(sdk) {
    const { defineComponent } = sdk;
    return [
        { def: defineComponent('WlPos', { x: 0, y: 0, z: 0 }, { replicatedFields: ['x', 'y', 'z'] }), fields: ['x', 'y', 'z'], mutated: true },
        { def: defineComponent('WlVitals', { hp: 100, mp: 50 }, { replicatedFields: ['hp', 'mp'] }), fields: ['hp', 'mp'], mutated: true },
        { def: defineComponent('WlMotion', { vx: 0, vy: 0 }, { replicatedFields: ['vx', 'vy'] }), fields: ['vx', 'vy'], mutated: true },
        { def: defineComponent('WlIdent', { team: 0, tag: '' }, { replicatedFields: ['team', 'tag'] }), fields: ['team', 'tag'], mutated: false },
    ];
}

/** Populate a world with `count` entities carrying every workload component. */
export function buildWorld(world, table, count) {
    const entities = new Array(count);
    for (let i = 0; i < count; i++) {
        const e = world.spawn();
        world.insert(e, table[0].def, { x: i, y: 0, z: 0 });
        world.insert(e, table[1].def, { hp: 100, mp: 50 });
        world.insert(e, table[2].def, { vx: 0, vy: 0 });
        world.insert(e, table[3].def, { team: i & 3, tag: 'unit' });
        entities[i] = e;
    }
    return entities;
}

/**
 * Apply one simulation tick's writes. Deterministic in `tick`: the same
 * entities take the same values in every arm, which is what makes the arms
 * comparable at all.
 */
export function applyTick(world, table, entities, tick, dirtyCount) {
    const n = entities.length;
    if (dirtyCount <= 0) return;
    // One access pattern at EVERY rate. A sequential special case for "all of
    // them" is cache-friendly in a way the strided rates are not, and read as
    // 100% dirty costing 43% LESS than 95%.

    // Modulo every step, not one subtraction: STRIDE outruns the smallest entity
    // count here, and an index that walks off the array writes nothing while
    // still reporting the dirty rate it never applied.
    let idx = (tick * STRIDE) % n;
    for (let k = 0; k < Math.min(dirtyCount, n); k++) {
        writeOne(world, table, entities, idx, tick);
        idx = (idx + STRIDE) % n;
    }
}

/** One entity's write: one of the three mutable components, values from tick. */
function writeOne(world, table, entities, i, tick) {
    const e = entities[i];
    switch ((tick + i) % 3) {
        case 0: world.set(e, table[0].def, { x: i + tick, y: tick, z: 0 }); break;
        case 1: world.set(e, table[1].def, { hp: 100 - (tick % 97), mp: 50 + (i % 13) }); break;
        default: world.set(e, table[2].def, { vx: (tick % 31) - 15, vy: (i % 17) - 8 }); break;
    }
}

// ---------------------------------------------------------------------------
// Shadow
// ---------------------------------------------------------------------------

/**
 * entity → componentIndex → { field: lastBroadcastValue }, SEEDED as production
 * seeds it at `registerEntity_`: first state ships in the spawn payload, so the
 * first sample owes nothing. An empty shadow instead emits the whole world once
 * and reads as a catastrophic tracker miss that is really the baseline.
 */
export function newShadow(world, entities, table) {
    const shadow = new Map();
    for (const e of entities) {
        const perComp = new Map();
        for (let ci = 0; ci < table.length; ci++) {
            const entry = table[ci];
            if (!world.has(e, entry.def)) continue;
            const data = world.tryGet(e, entry.def);
            const snap = {};
            for (const f of entry.fields) snap[f] = data[f];
            perComp.set(ci, snap);
        }
        shadow.set(e, perComp);
    }
    return shadow;
}

/**
 * Compare one entity's one component against its shadow, updating it. Returns
 * the changed-field mask (0 = nothing moved). This is the production
 * `collectDirty_` inner loop, reproduced so all four arms share it.
 */
function verify(world, entry, ci, e, perComp, out) {
    if (!world.has(e, entry.def)) return 0;
    const data = world.tryGet(e, entry.def);
    let snap = perComp.get(ci);
    if (!snap) { snap = {}; perComp.set(ci, snap); }
    let mask = 0;
    for (let f = 0; f < entry.fields.length; f++) {
        const key = entry.fields[f];
        const value = data[key];
        if (!(key in snap) || snap[key] !== value) {
            mask |= 1 << f;
            snap[key] = value;
        }
    }
    if (mask !== 0) out.push(e, ci, mask);
    return mask;
}

// ---------------------------------------------------------------------------
// The four arms
// ---------------------------------------------------------------------------

/** A/B — every known entity, every replicated component, every field. */
export function sampleFullShadow(world, table, entities, shadow, out) {
    let compares = 0;
    let visited = 0;
    for (let ci = 0; ci < table.length; ci++) {
        const entry = table[ci];
        for (let i = 0; i < entities.length; i++) {
            const e = entities[i];
            visited++;
            compares += entry.fields.length;
            verify(world, entry, ci, e, shadow.get(e), out);
        }
    }
    return { visited, compares };
}

/**
 * C — the tracker names candidates, the shadow still decides. Against the
 * ChangeTracker as it EXISTS: `anyChangedSince` gates a whole component in O(1),
 * but nothing indexes which entities changed, so the per-entity question is
 * still asked once per entity. Inventing that index would measure absent code.
 */
export function sampleTrackedCandidates(world, table, entities, shadow, since, out, recall) {
    let compares = 0;
    let visited = 0;
    let candidates = 0;
    for (let ci = 0; ci < table.length; ci++) {
        const entry = table[ci];
        if (!world.anyChangedSince(entry.def, since)) {
            if (recall) recall.skippedComponents++;
            continue;
        }
        for (let i = 0; i < entities.length; i++) {
            const e = entities[i];
            visited++;
            if (!world.isChangedSince(e, entry.def, since)) continue;
            candidates++;
            compares += entry.fields.length;
            verify(world, entry, ci, e, shadow.get(e), out);
        }
    }
    return { visited, compares, candidates };
}

/** D — candidates trusted outright. COUNTERFACTUAL: it assumes the very thing
 *  this probe is investigating. It bounds the ceiling, it justifies nothing. */
export function sampleTrackerOnly(world, table, entities, shadow, since, out) {
    let visited = 0;
    let candidates = 0;
    for (let ci = 0; ci < table.length; ci++) {
        const entry = table[ci];
        if (!world.anyChangedSince(entry.def, since)) continue;
        for (let i = 0; i < entities.length; i++) {
            const e = entities[i];
            visited++;
            if (!world.isChangedSince(e, entry.def, since)) continue;
            candidates++;
            const data = world.tryGet(e, entry.def);
            if (data) out.push(e, ci, (1 << entry.fields.length) - 1);
        }
    }
    return { visited, compares: 0, candidates };
}

// ---------------------------------------------------------------------------
// Output identity
// ---------------------------------------------------------------------------

/**
 * An order-sensitive digest of everything a sample emitted. Arms that claim to
 * produce the same replication output must produce the same number here, and it
 * crosses process boundaries, which in-process comparison cannot.
 */
export class Digest {
    constructor() { this.h = 0x811c9dc5; this.entries = 0; }
    push(entity, ci, mask) {
        this.entries++;
        this.mix(entity); this.mix(ci); this.mix(mask);
    }
    mix(v) {
        let h = this.h ^ (v >>> 0);
        h = Math.imul(h, 0x01000193);
        this.h = h >>> 0;
    }
    get value() { return this.h >>> 0; }
}