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.

7.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { App, Plugin } from '../app/app';
import { defineResource, Time } from '../ecs/resource';
import { Schedule, defineSystem } from '../ecs/system';
import { DeviceStatus, getDeviceStatus } from '../render/renderer';
import { Assets as AssetsClass } from './Assets';
import { HttpBackend } from './Backend';
import { basisTranscoderFor } from './basisWorkers';
import { bindAssetReferenceTracking } from './assetReferenceTracking';
import { Audio, type AudioAPI } from '../audio/Audio';
import { SpriteAnimation, type SpriteAnimationAPI } from '../animation/SpriteAnimator';
import { Localization, type LocalizationAPI } from '../i18n/Localization';
import { log } from '../util/logger';
import { disposeAll } from '../util/disposeAll';

interface AssetPluginState {
    created: AssetsClass;
    current: () => AssetsClass | null;
    released: boolean;
}

/**
 * The asset loader a system receives from `Res(Assets)`.
 *
 * `@beta`, and the evidence says so: of its members the certified corpus calls
 * four, and a third of the rest is the host wiring a runtime in — resolvers,
 * registries, the manifest, device-loss recovery — which is the embedding contract
 * rather than anything a game writes.
 *
 * @beta
 */
export type AssetsData = AssetsClass;

/**
 * The asset loader, as a resource. Rarely the door a game uses: scenes preload
 * what they reference and components resolve their own assets, so this is for the
 * cases that outlive a scene — hot updates, groups loaded on demand.
 *
 * @beta
 */
export const Assets = defineResource<AssetsData>(
    null!,
    'Assets'
);

export class AssetPlugin implements Plugin {
    name = 'asset';
    private readonly states_ = new WeakMap<App, AssetPluginState>();
    private latestState_: AssetPluginState | null = null;

    build(app: App): void {
        this.cleanup(app);
        const module = app.wasmModule;
        if (!module) {
            log.warn('asset', 'AssetPlugin: No WASM module available');
            return;
        }

        const assets = AssetsClass.create({
            backend: new HttpBackend({ baseUrl: '' }),
            module,
            getAudio: (): AudioAPI | null =>
                app.hasResource(Audio) ? app.getResource(Audio) : null,
            getSpriteAnimation: (): SpriteAnimationAPI | null =>
                app.hasResource(SpriteAnimation) ? app.getResource(SpriteAnimation) : null,
            getLocalization: (): LocalizationAPI | null =>
                app.hasResource(Localization) ? app.getResource(Localization) : null,
        });

        // Lazily acquire the Basis transcoder for KTX2 textures the same way
        // physics/spine acquire their modules — only when a compressed texture is
        // actually loaded. The closure defers to app.sideModules,
        // which the realm sets before any asset load.
        assets.getTextureLoader().setTranscoderProvider(() => basisTranscoderFor(app.sideModules));

        // Install the ref counter so scene spawning records live World IDs,
        // and wire it to world despawns so entries don't
        // outlive their entities. Tools / debug UI read it via
        // `assets.getRefCounter()`.
        bindAssetReferenceTracking(app.world, assets,
            () => app.hasResource(Assets) ? app.getResource(Assets) : null);

        app.insertResource(Assets, assets);
        const state: AssetPluginState = { created: assets,
            current: () => app.hasResource(Assets) ? app.getResource(Assets) : null, released: false };
        this.states_.set(app, state);
        this.latestState_ = state;
        this.driveDeviceRecovery_(app, state);
    }

    /** Release both the default loader and any runtime replacement owned by this App. */
    cleanup(app?: App): void {
        const state = app ? this.states_.get(app) : this.latestState_;
        if (!state || state.released) return;
        state.released = true;
        if (app) this.states_.delete(app);
        if (state === this.latestState_) this.latestState_ = null;
        const current = state.current();
        disposeAll(current && current !== state.created ? [state.created, current] : [state.created], assets => {
            try { assets.releaseAll(); } finally { assets.getRefCounter()?.clear(); }
        });
    }

    /**
     * Recovers the renderer after a device loss, which nothing did: the path
     * existed end to end with no caller but a test probe, so a shipped game that
     * lost its GPU stayed lost. Timed off UNSCALED delta — a paused game still
     * has to come back — and backed off, since each attempt re-fetches content.
     */
    private driveDeviceRecovery_(app: App, state: AssetPluginState): void {
        let inFlight = false;
        let waited = 0;
        let backoff = 0;
        let downtime = 0;

        app.addSystemToSchedule(Schedule.First, defineSystem([], () => {
            if (state.released) return;
            const status = getDeviceStatus();
            if (status === DeviceStatus.Live || status === DeviceStatus.Dead) {
                backoff = 0;
                waited = 0;
                downtime = 0;
                return;
            }
            const dt = app.getResource(Time)?.unscaledDelta ?? 0;
            downtime += dt;
            if (inFlight) return;
            waited += dt;
            if (waited < backoff) return;

            waited = 0;
            inFlight = true;
            const lostFor = downtime;
            // A runtime replaces the default HTTP-backed resource with its own
            // decoder. Never recover the instance captured during plugin build.
            const recoverCurrent = async (): Promise<boolean> => {
                let assets = app.hasResource(Assets) ? app.getResource(Assets) : null;
                while (assets && !state.released) {
                    const whole = await assets.recoverFromDeviceLoss();
                    if (state.released) return false;
                    const current = app.hasResource(Assets) ? app.getResource(Assets) : null;
                    if (current === assets) return whole;
                    assets = current;
                }
                return false;
            };
            void recoverCurrent()
                .then((whole) => {
                    if (state.released) return;
                    if (whole) {
                        log.info('asset', `Device recovered after ${lostFor.toFixed(1)}s`);
                        backoff = 0;
                        return;
                    }
                    backoff = Math.min(backoff ? backoff * 2 : RECOVERY_RETRY_S, RECOVERY_RETRY_MAX_S);
                })
                .catch((e) => {
                    if (state.released) return;
                    log.warn('asset', 'Device recovery threw; will retry', e);
                    backoff = Math.min(backoff ? backoff * 2 : RECOVERY_RETRY_S, RECOVERY_RETRY_MAX_S);
                })
                .finally(() => { inFlight = false; });
        }));
    }
}

/** First wait after a recovery attempt comes back incomplete, in seconds. */
const RECOVERY_RETRY_S = 0.25;
/** Ceiling for that wait: a context can take a while, but not minutes. */
const RECOVERY_RETRY_MAX_S = 5;

export const assetPlugin = new AssetPlugin();