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.

27.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    WorldStreamer.ts
 * @brief   The one thing that decides which cells of a cooked world exist.
 *
 * @details Residency has a single author. Renderers do not load places, AI does
 *          not unload them, and an entity never decides it is far enough away to
 *          delete itself — every one of those is a second author, and two authors
 *          of existence is how a world ends up holding entities nobody can name.
 *
 *          A cell is an additively-loaded scene, so bringing one in and taking it
 *          out is the scene lifecycle transaction that already exists: one
 *          teardown protocol, idempotent, with the cell's asset receipts owned by
 *          the cell's own scope. Unloading is a real destroy — not a visibility
 *          flag — which is the whole reason a cell is a scene rather than a list
 *          of things to hide.
 */

import { desiredResidency, type ResidencySource, type WorldCell, type WorldManifest } from './cells';
import type { SceneConfig } from '../scene/sceneManager';
import {
    sameReadiness, type RenderReadiness, type RenderReadinessStamp,
} from '../render/renderReadiness';
import { defineResource } from '../ecs/resource';
import { log } from '../util/logger';

/**
 * Where a cell is in its lifetime.
 *
 * `prepared` is the one worth naming: fetched, decoded, its assets acquired, and
 * carrying not one runtime entity. Nothing in the world can observe it, because
 * there is nothing there to observe.
 *
 * @experimental
 */
export type CellResidency =
    'unloaded' | 'preparing' | 'prepared' | 'publishing' | 'resident' | 'unloading';

/**
 * The slice of `SceneManager` the streamer drives. `SceneManagerState` satisfies
 * it structurally; a criterion injects a recording stub.
 *
 * @experimental
 */
export interface WorldStreamHost {
    register(config: SceneConfig): void;
    prepare(name: string): Promise<void>;
    /**
     * Make the render programs a prepared cell requires ready. Absent on a host
     * that predates the obligation, which reads as not applicable — the same
     * answer a headless one gives, and never a claim that succeeded.
     */
    readyRenderPrograms?(name: string): Promise<RenderReadiness>;
    discardPrepared(name: string): number;
    loadAdditive(name: string): Promise<unknown>;
    unload(name: string, options?: { keepPersistent?: boolean }): Promise<void>;
    isLoaded(name: string): boolean;
}

/** What the streamer is doing, for a report. @experimental */
export interface WorldStreamerStatus {
    cellCount: number;
    sourceCount: number;
    /** Cells that should exist right now, load radius unioned with the kept band. */
    desiredCells: string[];
    /** Cells worth readying: what any source is close enough to speculate about. */
    prefetchCells: string[];
    residentCells: string[];
    /** Ready and holding nothing the world can see. */
    preparedCells: string[];
    loadingCells: string[];
    unloadingCells: string[];
    /** Cells brought in since boot, and cells taken out. Churn is the difference. */
    loadCount: number;
    unloadCount: number;
    /** Preparations begun, and preparations thrown away unpublished. */
    prepareCount: number;
    cancelCount: number;
    /** Of those preparations, the ones begun for a cell nobody had asked for yet. */
    prefetchRequests: number;
    /** Acquisitions given back by discarding readiness — not by unloading. */
    cancelledRefs: number;
    /**
     * Decided the instant a cell is first DEMANDED, by what demand finds there:
     * readiness that already exists is a hit, and anything else — nothing, or a
     * preparation still in flight — is a miss. A preparation that was on its way
     * is not a hit: the player waited for it either way.
     */
    prefetchHits: number;
    prefetchMisses: number;
    /** Demanded to resident, milliseconds — what a prefetch hit is worth. */
    lastDemandToResidentMs: number;
}

interface CellState {
    cell: WorldCell;
    residency: CellResidency;
    /**
     * The obligations preparation owes before this cell may be called prepared.
     * Held here and only READ by the state machine: what a cell's programs are
     * is the renderer's question, and a streamer deriving it would be a second
     * author of the answer.
     */
    assetsReady: boolean;
    /** The claim, once one has been made. Null while it is still owed. */
    renderReadiness: RenderReadinessStamp | null;
    /** Whether a readying attempt is in flight, so a retry does not stack. */
    readinessInFlight: boolean;
    /** How often publication found the claim stale and replaced it. Zero over a
     *  dwell in which nothing moved is the whole point of preparing early. */
    restamps: number;
    /** What the last reconciliation asked for; the async completions re-read it. */
    desired: boolean;
    /** Whether any source is close enough to speculate about it. */
    speculated: boolean;
    /** Where this cell's last load spent its time, phase by phase. */
    phases: Record<string, number>;
    /** When the load was issued, so `delivery` is measured and not guessed. */
    issuedAt: number;
    /** Issue to resident, in wall time. Most of it is not the engine working. */
    delivery: number;
    /** When it became demanded, so the latency a player feels can be measured. */
    demandedAt: number;
    /** When readiness arrived, so how long it then sat unused is measurable. */
    preparedAt: number;
    /** When publication began, so the wait BEFORE it is not charged to it. */
    publishedAt: number;
    /** Issue to prepared: what a hit takes off the latency a player feels. */
    prepareMs: number;
    /** Publish to resident: what a hit still costs, whatever prefetch does. */
    publishMs: number;
    /** Demanded to resident — the whole of what a player waits through. */
    demandToResidentMs: number;
    /** Prepared to demanded. Only a hit has one; a miss had nothing waiting. */
    dwellMs: number;
    /** What the last demand for this cell found. */
    outcome: 'hit' | 'miss' | '';
}

/** Where one cell's last delivery spent its time. @experimental */
export interface CellDelivery {
    /** Phases of the preparation, which runs between frames and on no system timer. */
    phases: Record<string, number>;
    /** Issue to resident. For a hit this contains the dwell, so it is not a latency. */
    deliveryMs: number;
    prepareMs: number;
    publishMs: number;
    /** The latency a player feels: from wanting the place to standing in it. */
    demandToResidentMs: number;
    /** How long readiness waited to be wanted. Zero on a miss — nothing waited. */
    dwellMs: number;
    outcome: 'hit' | 'miss' | '';
}

export class WorldStreamer {
    private readonly host_: WorldStreamHost;
    private manifest_: WorldManifest | null = null;
    /** In manifest order, so every list this produces is stable. */
    private readonly cells_ = new Map<string, CellState>();
    private sourceCount_ = 0;
    private loadCount_ = 0;
    private unloadCount_ = 0;
    private prepareCount_ = 0;
    private cancelCount_ = 0;
    private cancelledRefs_ = 0;
    private prefetchRequests_ = 0;
    private prefetchHits_ = 0;
    private prefetchMisses_ = 0;
    private lastDemandToResident_ = 0;
    private readonly operations_ = new Set<Promise<void>>();
    private clearPromise_: Promise<void> | null = null;
    private clearing_ = false;
    private manifestRequest_ = 0;

    constructor(host: WorldStreamHost) {
        this.host_ = host;
    }

    /** Adopt a cooked world after the previous world's operations and receipts drain. The latest request wins. */
    async loadManifest(manifest: WorldManifest, sceneConfig?: (cell: WorldCell) => SceneConfig): Promise<void> {
        const request = ++this.manifestRequest_;
        if (this.cells_.size > 0 || this.clearing_) await this.clearCells_();
        if (request !== this.manifestRequest_) return;
        this.manifest_ = manifest;
        this.cells_.clear();
        for (const cell of manifest.cells) {
            this.host_.register(sceneConfig?.(cell) ?? { name: cell.name, path: cell.path });
            this.cells_.set(cell.name, {
                cell, residency: 'unloaded', desired: false, speculated: false,
                assetsReady: false, renderReadiness: null, readinessInFlight: false,
                restamps: 0,
                phases: {}, issuedAt: 0, delivery: 0,
                demandedAt: 0, preparedAt: 0, publishedAt: 0,
                prepareMs: 0, publishMs: 0, demandToResidentMs: 0, dwellMs: 0, outcome: '',
            });
        }
    }

    get manifest(): WorldManifest | null {
        return this.manifest_;
    }

    residencyOf(name: string): CellResidency {
        return this.cells_.get(name)?.residency ?? 'unloaded';
    }

    /**
     * The render-program claim a cell holds, or null when it holds none.
     *
     * A cell on a host with no renderer holds NONE — the obligation did not
     * apply, which is a different fact from a claim that succeeded and must stay
     * distinguishable from one. Publication reads this to re-check freshness.
     *
     * @experimental
     */
    renderReadinessOf(name: string): RenderReadinessStamp | null {
        return this.cells_.get(name)?.renderReadiness ?? null;
    }

    /**
     * How often publication found this cell's claim stale and made a new one.
     *
     * Zero across a dwell where nothing moved: readying again for content that
     * did not change is the cost prefetching exists to avoid paying twice.
     *
     * @experimental
     */
    restampsOf(name: string): number {
        return this.cells_.get(name)?.restamps ?? 0;
    }

    /**
     * Where a cell's load spent its time.
     *
     * Most of a load runs BETWEEN frames — off every system timer there is — so a
     * profiler watching the frame loop sees the cost and cannot name it.
     */
    recordPhase(name: string, phase: string, ms: number): void {
        const state = this.cells_.get(name);
        if (state) state.phases[phase] = (state.phases[phase] ?? 0) + ms;
    }

    /**
     * Per cell: where its last delivery spent its time.
     *
     * Per CELL and not a running average, because the question prefetch answers
     * is asked one arrival at a time: a mean over hits and misses together
     * describes no arrival that happened.
     */
    delivery(): Record<string, CellDelivery> {
        const out: Record<string, CellDelivery> = {};
        for (const [name, state] of this.cells_) {
            if (state.delivery === 0 && Object.keys(state.phases).length === 0) continue;
            out[name] = {
                phases: { ...state.phases },
                deliveryMs: state.delivery,
                prepareMs: state.prepareMs,
                publishMs: state.publishMs,
                demandToResidentMs: state.demandToResidentMs,
                dwellMs: state.dwellMs,
                outcome: state.outcome,
            };
        }
        return out;
    }

    /**
     * Reconcile residency against where the sources are.
     *
     * The sources arrive as a list and are unioned, never folded: a fold gives
     * the last one written the whole answer, and then a second camera deletes
     * the world the first is standing in.
     */
    update(sources: readonly ResidencySource[]): void {
        if (this.clearing_) return;
        this.sourceCount_ = sources.length;
        if (this.cells_.size === 0) return;
        const resident = new Set<string>();
        for (const [name, state] of this.cells_) {
            // Publishing counts as resident so the decision does not ask twice, and
            // unloading does not, so a source that came back re-issues the load.
            if (state.residency === 'resident' || state.residency === 'publishing') resident.add(name);
        }
        const cells: WorldCell[] = [];
        for (const state of this.cells_.values()) cells.push(state.cell);
        const decision = desiredResidency(cells, sources, resident);

        const target = new Set(decision.target);
        const speculated = new Set(decision.prefetch);
        const now = performance.now();
        for (const [name, state] of this.cells_) {
            const wanted = target.has(name);
            if (wanted && !state.desired) this.demand_(state, now);
            state.desired = wanted;
            state.speculated = speculated.has(name);
        }
        // Demanded first and nearest first: a place a player is walking into
        // outranks one they might. Then speculation, then what nobody needs.
        for (const name of decision.toLoad) this.step_(name);
        for (const name of decision.prefetch) if (!target.has(name)) this.step_(name);
        for (const name of decision.toUnload) this.step_(name);
        for (const [name, state] of this.cells_) {
            if ((state.residency === 'prepared' || state.residency === 'preparing') && !state.desired && !state.speculated) {
                this.step_(name);
            }
        }
    }

    /** Drain every cell and preparation; registrations remain reusable by a later update. Cancels pending adoption. */
    clear(): Promise<void> {
        this.manifestRequest_++;
        return this.clearCells_();
    }

    private clearCells_(): Promise<void> {
        if (this.clearPromise_) return this.clearPromise_;
        this.clearing_ = true;
        this.sourceCount_ = 0;
        for (const state of this.cells_.values()) {
            state.desired = false;
            state.speculated = false;
        }
        this.clearPromise_ = (async () => {
            for (const name of this.cells_.keys()) this.step_(name);
            // Publication may finish by starting an unload, so drain the entire chain.
            while (this.operations_.size > 0) await Promise.allSettled([...this.operations_]);
            const remaining = [...this.cells_].filter(([, state]) => state.residency !== 'unloaded');
            if (remaining.length > 0) throw new Error(`World residency could not release: ${remaining.map(([name]) => name).join(', ')}`);
        })().finally(() => {
            this.clearing_ = false;
            this.clearPromise_ = null;
        });
        return this.clearPromise_;
    }

    /** Track host operations through their completion handlers so replacement cannot reuse a live scene name. */
    private run_<T>(action: () => Promise<T>, done: (value: T) => void, failed: (error: unknown) => void): void {
        let result: Promise<T>;
        try { result = Promise.resolve(action()); } catch (error) { result = Promise.reject(error); }
        const operation = result.then(done, failed);
        this.operations_.add(operation);
        void operation.then(
            () => { this.operations_.delete(operation); },
            error => {
                this.operations_.delete(operation);
                log.error('residency', 'cell completion failed', error);
            },
        );
    }

    status(): WorldStreamerStatus {
        const desiredCells: string[] = [];
        const prefetchCells: string[] = [];
        const residentCells: string[] = [];
        const preparedCells: string[] = [];
        const loadingCells: string[] = [];
        const unloadingCells: string[] = [];
        for (const [name, state] of this.cells_) {
            if (state.desired) desiredCells.push(name);
            if (state.speculated) prefetchCells.push(name);
            if (state.residency === 'resident') residentCells.push(name);
            else if (state.residency === 'prepared') preparedCells.push(name);
            else if (state.residency === 'preparing' || state.residency === 'publishing') {
                loadingCells.push(name);
            } else if (state.residency === 'unloading') unloadingCells.push(name);
        }
        return {
            cellCount: this.cells_.size,
            sourceCount: this.sourceCount_,
            desiredCells, prefetchCells, residentCells, preparedCells,
            loadingCells, unloadingCells,
            loadCount: this.loadCount_, unloadCount: this.unloadCount_,
            prepareCount: this.prepareCount_, cancelCount: this.cancelCount_,
            prefetchRequests: this.prefetchRequests_,
            cancelledRefs: this.cancelledRefs_,
            prefetchHits: this.prefetchHits_, prefetchMisses: this.prefetchMisses_,
            lastDemandToResidentMs: this.lastDemandToResident_,
        };
    }

    /**
     * A cell has just been asked for, and what the ask FINDS is the hit.
     *
     * Not judged at publication: "prepared by the time we published it" is true
     * of every cell that ever loads. Only readiness that already existed when
     * the ask arrived took anything off the wait.
     */
    private demand_(state: CellState, now: number): void {
        state.demandedAt = now;
        // Already here, or already on its way in: this ask owes no publication,
        // so there is nothing for speculation to have been early for.
        if (state.residency === 'resident' || state.residency === 'publishing') return;
        if (state.residency === 'prepared') {
            this.prefetchHits_++;
            state.outcome = 'hit';
            state.dwellMs = now - state.preparedAt;
        } else {
            this.prefetchMisses_++;
            state.outcome = 'miss';
            state.dwellMs = 0;
        }
    }

    /**
     * Move one cell toward what it should be, or leave it alone while an earlier
     * move is still in flight. Re-entered when that move finishes, which is what
     * lets a source that turned around re-issue the opposite one — without this,
     * a cell whose load was overtaken stays resident forever.
     */
    private step_(name: string): void {
        const state = this.cells_.get(name);
        if (!state) return;
        if (state.readinessInFlight) return;
        if (state.residency === 'preparing') {
            // Assets are in and only the program obligation is left. Retried
            // here, because a claim refused once (a device that rebuilt mid-
            // readying) costs one more attempt rather than the whole preparation.
            if (state.assetsReady) {
                if (!state.desired && !state.speculated) this.discardPrepared_(name, state);
                else this.settleReadiness_(name, state);
            }
            return;
        }
        if (state.residency === 'publishing' || state.residency === 'unloading') return;
        if (state.residency === 'unloaded' && (state.desired || state.speculated)) {
            this.beginPrepare_(name, state);
        } else if (state.residency === 'prepared' && state.desired) {
            this.publishWhenReady_(name, state);
        } else if (state.residency === 'prepared' && !state.speculated) {
            // Speculation is not authority. A cell nobody is near any more goes
            // back, receipts included, rather than being published because it
            // happens to be ready.
            this.discardPrepared_(name, state);
        } else if (state.residency === 'resident' && !state.desired) {
            this.beginUnload_(name, state);
        }
    }

    private discardPrepared_(name: string, state: CellState): void {
        this.cancelledRefs_ += this.host_.discardPrepared(name);
        state.residency = 'unloaded';
        state.assetsReady = false;
        state.renderReadiness = null;
        this.cancelCount_++;
    }

    private beginPrepare_(name: string, state: CellState): void {
        state.residency = 'preparing';
        state.phases = {};
        state.issuedAt = performance.now();
        state.prepareMs = 0;
        state.publishMs = 0;
        state.demandToResidentMs = 0;
        this.prepareCount_++;
        if (!state.desired) {
            // Speculating afresh about a cell whose last delivery is over. Its
            // verdict belonged to THAT delivery, and carrying it forward would
            // report a hit for an ask nobody has made yet.
            this.prefetchRequests_++;
            state.outcome = '';
            state.dwellMs = 0;
        }
        state.assetsReady = false;
        state.renderReadiness = null;
        this.run_(() => this.host_.prepare(name),
            () => {
                // One obligation of two. `prepared` is not the end of the assets
                // arriving, it is the end of everything publication requires.
                state.assetsReady = true;
                this.step_(name);
            },
            (err) => {
                state.residency = 'unloaded';
                state.assetsReady = false;
                log.error('residency', `cell "${name}" did not prepare`, err);
            },
        );
    }

    /**
     * Pay the render-program obligation, or leave it owed.
     *
     * A debt rather than an event: a claim that could not be made leaves the cell
     * in `preparing` with its assets intact, and the next progression tries
     * again. Dropping it would strip a preparation that had almost finished.
     */
    private settleReadiness_(name: string, state: CellState): void {
        const ready = this.host_.readyRenderPrograms;
        if (!ready) { this.markPrepared_(name, state); return; }

        state.readinessInFlight = true;
        this.run_(() => this.askReadiness_(name, ready),
            (outcome) => {
                state.readinessInFlight = false;
                if (!state.desired && !state.speculated) { this.discardPrepared_(name, state); return; }
                // Not applicable is an answer, not a claim: a host with no
                // renderer has nothing to ready and owes nothing.
                if (!outcome.applicable) { this.markPrepared_(name, state); return; }
                if (!outcome.stamp) {
                    log.warn('residency',
                             `cell "${name}" readied no render programs; still owed`);
                    return;
                }
                state.renderReadiness = outcome.stamp;
                this.markPrepared_(name, state);
            },
            (err) => {
                state.readinessInFlight = false;
                log.error('residency', `cell "${name}" could not ready its programs`, err);
                if (!state.desired && !state.speculated) this.step_(name);
            },
        );
    }

    /**
     * Ask the host to ready a cell's programs, as a promise either way.
     *
     * A host that throws SYNCHRONOUSLY would otherwise unwind through the
     * progression and leave the streamer mid-step. A failed readying is an
     * outcome this handles, not one it propagates.
     */
    private askReadiness_(
        name: string, ready: NonNullable<WorldStreamHost['readyRenderPrograms']>,
    ): Promise<RenderReadiness> {
        // Timed around the CALL, not the settle: the readying is synchronous work
        // behind an async signature, so waiting on the promise measures how busy
        // the thread was afterwards — 6 ms of compile read as 52 on a busy arrival.
        const began = performance.now();
        try {
            return Promise.resolve(ready.call(this.host_, name));
        } catch (err) {
            return Promise.reject(err);
        } finally {
            this.recordPhase(name, 'readying', performance.now() - began);
        }
    }

    /** Every obligation is satisfied: only now is the cell prepared. */
    private markPrepared_(name: string, state: CellState): void {
        state.residency = 'prepared';
        state.preparedAt = performance.now();
        state.prepareMs = state.preparedAt - state.issuedAt;
        // What finished was begun against a world that has moved. Whether this
        // cell is still wanted — or wanted now when it was not — is asked again
        // here rather than assumed from when it started.
        this.step_(name);
    }

    /**
     * The obligation publication has, which is not the one preparation had.
     *
     * A claim about THEN, so requirements are derived AGAIN rather than inferred
     * from what looks like it moved. A stale one blocks this publication without
     * sending the cell backwards; an unpayable debt leaves it prepared.
     */
    private publishWhenReady_(name: string, state: CellState): void {
        const ready = this.host_.readyRenderPrograms;
        // No claim to keep fresh: the obligation did not apply when this cell was
        // prepared, and nothing since then has given it a renderer.
        if (!ready || !state.renderReadiness) { this.beginLoad_(name, state); return; }
        if (state.readinessInFlight) return;

        state.readinessInFlight = true;
        this.run_(() => this.askReadiness_(name, ready),
            (outcome) => {
                state.readinessInFlight = false;
                if (!state.desired) { this.step_(name); return; }
                if (!outcome.applicable) { this.beginLoad_(name, state); return; }
                if (!outcome.stamp) {
                    // Publication created a debt of its own — the readying was
                    // refused, most likely by a device that moved underneath it.
                    log.warn('residency',
                             `cell "${name}" cannot publish: its programs are not ready`);
                    return;
                }
                // Compared, not merely overwritten: re-readying is idempotent so
                // both paths publish, but comparing BOTH halves is what keeps
                // either half from silently coming undone.
                if (!sameReadiness(state.renderReadiness!, outcome.stamp)) {
                    state.renderReadiness = outcome.stamp;
                    state.restamps++;
                }
                this.beginLoad_(name, state);
            },
            (err) => {
                state.readinessInFlight = false;
                log.error('residency', `cell "${name}" could not re-ready its programs`, err);
                if (!state.desired) this.step_(name);
            },
        );
    }

    private beginLoad_(name: string, state: CellState): void {
        state.residency = 'publishing';
        state.publishedAt = performance.now();
        this.loadCount_++;
        this.run_(() => this.host_.loadAdditive(name),
            () => {
                const now = performance.now();
                state.residency = 'resident';
                state.delivery = now - state.issuedAt;
                state.publishMs = now - state.publishedAt;
                if (state.demandedAt > 0) {
                    state.demandToResidentMs = now - state.demandedAt;
                    this.lastDemandToResident_ = state.demandToResidentMs;
                }
                this.step_(name);
            },
            (err) => {
                // A cell that failed to come up owns nothing (the scene load is a
                // transaction), so it goes back to being absent and may be asked
                // for again rather than being stuck half-present.
                state.residency = 'unloaded';
                log.error('residency', `cell "${name}" did not load`, err);
            },
        );
    }

    private beginUnload_(name: string, state: CellState): void {
        state.residency = 'unloading';
        this.unloadCount_++;
        // `keepPersistent: false` is the contract: a cell's unload takes everything
        // the cell brought. Scene persistence answers a different question, and
        // honouring it here leaves exactly what residency exists to remove.
        this.run_(() => this.host_.unload(name, { keepPersistent: false }),
            () => { state.residency = 'unloaded'; this.step_(name); },
            (err) => {
                state.residency = this.host_.isLoaded(name) ? 'resident' : 'unloaded';
                log.error('residency', `cell "${name}" did not unload`, err);
            },
        );
    }
}

/** The world's residency authority. @experimental */
export const WorldStreaming = defineResource<WorldStreamer>(null!, 'WorldStreaming');