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.

12.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    registryAssets.ts
 * @brief   The identity of an asset a component names by REF rather than by handle.
 *
 * @details Two asset models had one ownership vocabulary between them. A sprite
 *          holds `texture = 17`: the field names an exact instance, so its owner
 *          holds a receipt for that generation. A `SpriteAnimator` holds
 *          `clip = "walk.esanim"`: the field names an asset, and every lookup
 *          asks a registry which object that name means NOW. Such a holder never
 *          had a generation to own — give it one and the moment a hot update
 *          republishes, ownership says one era while the component uses another.
 *
 *          So what it owns is the SLOT: the stable name, however many eras pass
 *          under it. An era owns what it acquired for itself and nothing else —
 *          publication belongs to the slot, which is what makes it impossible
 *          for a retiring era to unpublish the newer one that replaced it.
 *
 *          A lookup identity is (asset TYPE, logical name). Bare names would
 *          have two kinds of asset sharing one entry the moment a project's own
 *          registry-backed type answered to a name an engine one already used —
 *          today that is only prevented by the file extensions differing.
 */
import type { AssetLease } from './AssetLease';
import type { DependencyReceipt, Preparation } from './dependencies';
import { disposeAll } from '../util/disposeAll';

const releaseEra = (era: Preparation | null): void => era?.dependencies.releaseAll();

/** What one preparation PRODUCED. What it took is recorded for it — see
 *  dependencies.ts — so an era cannot describe a dependency it does not have. */
export interface RegistryEra<T> {
    /** The runtime object a lookup returns while this era is the published one. */
    readonly published: unknown;
    /** The logical identity a holder keeps — the same across every era. */
    readonly value: T;
}

/** One era, with what its preparation took. */
export type PreparedEra<T> = RegistryEra<T> & Preparation;

/** How one kind of registry-backed asset is prepared. Publishing is the slot's:
 *  it holds the era and answers the lookup, so there is nowhere else to write. */
export interface RegistryAssetKind<T> {
    prepare(path: string): Promise<PreparedEra<T>>;
}

/** A holder's claim on a slot. Its `generation` names the SLOT, not an era —
 *  which era is current is the slot's business and changes under the holder. */
export interface RegistrySlotLease<T> extends AssetLease<T> {
    /** Every name that resolves to this slot: the load path and its aliases. */
    readonly names: readonly string[];
}

export function isRegistrySlotLease(lease: AssetLease): lease is RegistrySlotLease<unknown> {
    return Array.isArray((lease as { names?: unknown }).names);
}

class Slot<T> {
    /** What a lookup asks for. Distinct from `key`, which is what an OWNER
     *  holds: a registry answers to a ref, not to an ownership identity. */
    readonly names: string[] = [];
    refs = 0;
    era: PreparedEra<T> | null = null;
    loading: Promise<PreparedEra<T>> | null = null;
    /** Which refresh is the current one. A preparation that started before the
     *  count moved is answering a question nobody is asking any more. */
    refresh = 0;

    constructor(readonly type: string, readonly key: string, readonly id: number) {}
}

/**
 * Every registry-backed asset this Assets has published, by every name that
 * resolves to it.
 */
/** One lookup identity. `\0` cannot occur in a path or a ref. */
function lookupKey(type: string, name: string): string {
    return `${type}\0${name}`;
}

export class RegistryAssetSlots {
    /** By (type, name) — see the note on lookup identity above. */
    private byName_ = new Map<string, Slot<unknown>>();
    private nextId_ = 1;
    private versions_ = new Map<string, number>();

    /** Publication counter; failed preparations and additional holders do not change it. */
    version(type: string): number { return this.versions_.get(type) ?? 0; }

    private changed_(type: string): void {
        this.versions_.set(type, this.version(type) + 1);
    }

    /**
     * A claim on the slot `key` identifies, publishing its first era if there is
     * none. `names` are what the registry answers to — the load path and every
     * ref a component may spell it as, all resolving to the SAME slot rather
     * than to a copy of the object.
     */
    async acquire<T>(
        kind: RegistryAssetKind<T>, type: string, key: string, names: readonly string[],
    ): Promise<RegistrySlotLease<T>> {
        const slot = this.slotFor_(type, key) as Slot<T>;
        for (const name of names) this.name_(slot as Slot<unknown>, type, name);

        if (!slot.era) {
            slot.loading ??= kind.prepare(key);
            let era: PreparedEra<T>;
            try {
                era = await slot.loading;
            } catch (e) {
                slot.loading = null;
                if (slot.refs === 0) this.forget_(slot as Slot<unknown>);
                throw e;
            }
            slot.loading = null;
            // The realm can have let go of everything while this prepared. The
            // slot is off the table, so publishing into it would hand a lease on
            // an era nothing resolves to and nobody will ever release.
            if (this.byName_.get(lookupKey(type, key)) !== slot) {
                era.dependencies.releaseAll();
                throw new Error(`"${key}" was released while it was loading; it has no owner. Load it again.`);
            }
            // Another acquire may have published while this one awaited; joining
            // it is a cache hit, and publishing twice would retire what is live.
            if (!slot.era) {
                slot.era = era;
                this.changed_(type);
            } else if (era !== slot.era) {
                era.dependencies.releaseAll();
            }
        }
        return this.lease_(kind, slot);
    }

    /**
     * Replace the current era with a freshly prepared one, atomically.
     *
     * A failed prepare leaves the slot exactly as it was — holders keep working
     * with the era they have rather than losing it to a bad download. Answers
     * false when nothing holds this name, and when what came back is no longer
     * the answer to any live question.
     */
    async republish<T>(kind: RegistryAssetKind<T>, type: string, name: string): Promise<boolean> {
        const slot = this.byName_.get(lookupKey(type, name)) as Slot<T> | undefined;
        if (!slot?.era) return false;
        const ticket = ++slot.refresh;
        const era = await kind.prepare(slot.key);
        if (era.failedDependencies?.length) {
            era.dependencies.releaseAll();
            throw new Error(`Cannot refresh "${name}": dependencies did not load: ${era.failedDependencies.join(', ')}`);
        }
        // Two things can have happened while this prepared: a newer refresh
        // started, or the last holder let go. Publishing either way puts an era
        // where nothing will ever release it.
        if (ticket !== slot.refresh || !slot.era) {
            era.dependencies.releaseAll();
            return false;
        }
        const previous = slot.era;
        slot.era = era;
        this.changed_(type);
        // Its dependencies only: what the name resolves to is the slot's, and
        // the era above already holds it.
        previous.dependencies.releaseAll();
        return true;
    }

    /** Whether this name is one a slot of this type answers to. */
    has(type: string, name: string): boolean {
        return this.byName_.has(lookupKey(type, name));
    }

    /** What the current era of (type, name) took — the graph, as a projection
     *  of acquisitions rather than a table anyone maintains. */
    dependenciesOf(type: string, name: string): readonly DependencyReceipt[] {
        return this.byName_.get(lookupKey(type, name))?.era?.edges ?? [];
    }

    /** Every live era, by the key its slot is filed under. What a reverse walk
     *  reads: who depends on what is computed from the eras themselves. */
    eras(): Array<{ type: string; key: string; edges: readonly DependencyReceipt[] }> {
        const out: Array<{ type: string; key: string; edges: readonly DependencyReceipt[] }> = [];
        for (const slot of new Set(this.byName_.values())) {
            if (slot.era) out.push({ type: slot.type, key: slot.key, edges: slot.era.edges });
        }
        return out;
    }

    /**
     * What this realm publishes for (type, name) right now — the answer a
     * runtime lookup reads, and the only copy of it.
     */
    published(type: string, name: string): unknown {
        return this.byName_.get(lookupKey(type, name))?.era?.published;
    }

    /** Everything published of one type. What a schedule analysis reads to learn
     *  what the loaded graphs of this realm reach for. */
    publishedOf(type: string): unknown[] {
        const out: unknown[] = [];
        for (const slot of new Set(this.byName_.values())) {
            if (slot.type === type && slot.era) out.push(slot.era.published);
        }
        return out;
    }

    /** Live slots — one per asset, however many names it answers to. */
    get size(): number {
        return new Set(this.byName_.values()).size;
    }

    /** Give up every slot. For a wholesale teardown. */
    releaseAll(): void {
        const eras: Array<Preparation | null> = [];
        for (const slot of new Set(this.byName_.values())) {
            eras.push(slot.era);
            if (slot.era) this.changed_(slot.type);
            slot.era = null;
            slot.refs = 0;
        }
        this.byName_.clear();
        disposeAll(eras, releaseEra);
    }

    /** Drop one claim on the slot `name` resolves to, without its receipt. The
     *  compatibility door for a caller that only ever had a path. */
    releaseByName(type: string, name: string): boolean {
        const slot = this.byName_.get(lookupKey(type, name));
        if (!slot || slot.refs === 0) return false;
        this.drop_(slot);
        return true;
    }

    private lease_<T>(kind: RegistryAssetKind<T>, slot: Slot<T>): RegistrySlotLease<T> {
        slot.refs++;
        let spent = false;
        const lease: RegistrySlotLease<T> = {
            key: slot.key,
            generation: slot.id,
            value: slot.era!.value,
            get failedDependencies() { return slot.era?.failedDependencies; },
            names: slot.names,
            release: () => {
                if (spent) return;
                spent = true;
                this.drop_(slot as Slot<unknown>);
            },
            retain: () => (this.byName_.get(lookupKey(slot.type, slot.key)) === (slot as Slot<unknown>) && slot.era
                ? this.lease_(kind, slot)
                : null),
        };
        return lease;
    }

    private drop_(slot: Slot<unknown>): void {
        if (slot.refs === 0) return; // A wholesale release already retired it.
        if (--slot.refs > 0) return;
        const era = slot.era;
        slot.era = null;
        if (era) this.changed_(slot.type);
        this.forget_(slot);
        releaseEra(era);
    }

    private slotFor_(type: string, key: string): Slot<unknown> {
        const id = lookupKey(type, key);
        let slot = this.byName_.get(id);
        if (!slot) {
            slot = new Slot<unknown>(type, key, this.nextId_++);
            this.byName_.set(id, slot);
        }
        return slot;
    }

    /**
     * Index another lookup name onto this slot, and publish under it too.
     *
     * The dedupe is on the NAME list, not on the index: the slot's own key is
     * already indexed when it is created, and reading that back as "already
     * known" left the list — which is what gets published — empty.
     */
    private name_(slot: Slot<unknown>, type: string, name: string): void {
        if (!slot.names.includes(name)) slot.names.push(name);
        this.byName_.set(lookupKey(type, name), slot);
    }

    private forget_(slot: Slot<unknown>): void {
        for (const [name, held] of [...this.byName_]) {
            if (held === slot) this.byName_.delete(name);
        }
    }
}