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.

5.7 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 two ways of finding which
 *        entities entered or left replication.
 *
 * The question is registry lifecycle, not field values: nothing here writes a
 * replicated field. Membership churn is a pure function of the tick, so two
 * processes cannot drift apart.
 */
import { pathToFileURL } from 'node:url';
import { readdirSync, statSync } from 'node:fs';
import path from 'node:path';

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


/**
 * For each component, the entities whose MEMBERSHIP moved, and from which tick
 * each reader still needs them. Deliberately not "added" and "removed" as
 * separate records: the registry re-reads the world rather than acting on what
 * history says, so "worth re-checking" is the whole requirement.
 */
export class TopologyJournal {
    #rows = [];
    #retainFrom = 0;

    /** One membership event. This is the write tax the B arm isolates. */
    record(entity, tick) {
        this.#rows.push({ entity, tick });
    }

    /** Entities worth re-checking since `floor` (strict `>`, as the tracker is). */
    since(floor) {
        const out = new Set();
        for (const row of this.#rows) if (row.tick > floor) out.add(row.entity);
        return out;
    }

    /** Give up everything through `lastTick`, as a reader-owned claim does. */
    advance(lastTick) {
        this.#retainFrom = lastTick + 1;
        let w = 0;
        for (let i = 0; i < this.#rows.length; i++) {
            if (this.#rows[i].tick >= this.#retainFrom) this.#rows[w++] = this.#rows[i];
        }
        this.#rows.length = w;
    }

    get size() { return this.#rows.length; }
}

/** The server's view: which entities the clients have been told exist. */
export class Registry {
    known = new Set();
    knownNetIds = new Map();
    #nextNetId = 1;

    register(e) {
        this.known.add(e);
        this.knownNetIds.set(e, this.#nextNetId++);
    }

    unregister(e) {
        const netId = this.knownNetIds.get(e);
        this.known.delete(e);
        this.knownNetIds.delete(e);
        return netId;
    }
}

/**
 * `count` entities carrying Replicated, and a dormant pool the churn moves them
 * into and out of. Dormant entities still EXIST — losing the component and being
 * despawned are different events, and the reducer has to answer for both.
 */
export function buildPopulation(sdk, world, count) {
    const live = [];
    const dormant = [];
    for (let i = 0; i < count; i++) {
        const e = world.spawn();
        world.insert(e, sdk.Replicated, { owner: 0 });
        live.push(e);
    }
    return { live, dormant };
}

/**
 * One tick's membership churn, deterministic in `tick`. Four shapes in rotation
 * so every cell of the reducer is exercised: leaving, returning, dying, and
 * being born already replicated.
 */
export function applyChurn(sdk, world, pop, tick, count, journal) {
    for (let k = 0; k < count; k++) {
        const shape = (tick + k) % 4;
        if (shape === 0 && pop.live.length > 1) {
            const e = pop.live.pop();
            world.remove(e, sdk.Replicated);
            pop.dormant.push(e);
            journal?.record(e, world.getWorldTick());
        } else if (shape === 1 && pop.dormant.length > 0) {
            const e = pop.dormant.pop();
            world.insert(e, sdk.Replicated, { owner: 0 });
            pop.live.push(e);
            journal?.record(e, world.getWorldTick());
        } else if (shape === 2 && pop.live.length > 1) {
            const e = pop.live.pop();
            world.despawn(e);
            journal?.record(e, world.getWorldTick());
        } else {
            const e = world.spawn();
            world.insert(e, sdk.Replicated, { owner: 0 });
            pop.live.push(e);
            journal?.record(e, world.getWorldTick());
        }
    }
}

/**
 * Today's reconcile: read every replicated entity, then walk the registry.
 * O(population) whether anything moved or not.
 */
export function reconcileFull(sdk, world, registry) {
    const current = world.getEntitiesWithComponents([sdk.Replicated]);
    const currentSet = new Set(current);
    const spawned = [];
    const despawned = [];
    for (const e of current) {
        if (!registry.known.has(e)) { registry.register(e); spawned.push(e); }
    }
    for (const e of [...registry.known]) {
        if (!currentSet.has(e) || !world.valid(e)) {
            const netId = registry.unregister(e);
            if (netId !== undefined) despawned.push({ entity: e, netId });
        }
    }
    return { spawned, despawned, visited: current.length + registry.known.size };
}

/**
 * The candidate reducer: the journal says who to re-check, and `known × current
 * world` says what is true. A membership that left and came back before the
 * sample is one candidate that is known and live — so, nothing.
 */
export function reconcileIncremental(sdk, world, registry, journal, floor) {
    const candidates = journal.since(floor);
    const spawned = [];
    const despawned = [];
    for (const e of candidates) {
        const isKnown = registry.known.has(e);
        // `valid` is belt to `has`'s braces — an entity id carries its generation,
        // so a stale handle misses the storage map anyway. Sabotaging it alone
        // does NOT redden this probe; see the README.
        const isLive = world.valid(e) && world.has(e, sdk.Replicated);
        if (!isKnown && isLive) { registry.register(e); spawned.push(e); }
        else if (isKnown && !isLive) {
            const netId = registry.unregister(e);
            if (netId !== undefined) despawned.push({ entity: e, netId });
        }
    }
    return { spawned, despawned, visited: candidates.size };
}