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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Backend } from './Backend';
import { packedBackend } from './packedBackend';
import { Catalog, type AtlasFrameInfo } from './Catalog';
import { ManifestModel, normalizeBundleMode, type AddressableManifest, type AddressableAssetType } from './AddressableManifest';
import { diffManifests, type UpdatePlan, type AssetChange } from './hotUpdate';
import { contentHashHex } from './contentHash';
import { encodeUtf8 } from '../util/utf8';
import { getPlatform, isPlatformInitialized } from '../platform/base';
import { contentCacheFor, type CacheVersion, type ContentCacheReport, type CacheCleanupResult } from '../platform/contentCache';
import { platformLoadSubpackage, platformGetStorageItem, platformSetStorageItem, platformRemoveStorageItem, platformWriteCacheFile } from '../platform';
import type {
AssetLoader, LoadContext, TextureResult, SpineResult,
MaterialResult, FontResult, AudioResult, AnimClipResult,
TilemapResult, TilesetResult, TimelineResult, PrefabResult,
LocaleResult, FsmResult, BtResult, AnimatorControllerResult, JsonResult,
} from './AssetLoader';
import { AsyncCache } from './AsyncCache';
import { TextureContent, textureContentName, type ESEngineModule } from '../wasm';
import type { CppResourceManager } from '../wasm';
import { requireResourceManager, getResourceManager, evictTextureDimensions, textureRefill } from '../wasm/resourceManager';
import type { TextureImportSettings, TextureImportSettingsResolver } from './loaders/TextureLoader';
import type { TextureFormatReport } from './textureFormatReport';
import { TextureLoader, textureResidencyKey } from './loaders/TextureLoader';
import { AssetRefLedger, type AssetRefLease } from './AssetRefLedger';
import { optionalAssetLoaders } from './optionalLoaders';
import { AssetScope, ownedAssetLease, type AssetLease } from './AssetLease';
import { EntityAssetScopes } from './entityAssetScopes';
import { RegistryAssetSlots, type RegistryAssetKind } from './registryAssets';
import { DependencyRecorder, PreparationFailure, preparationFailureReason, isInvalidatable, rebuildPlan, type AssetIdentity,
type DependencyReceipt, type Preparation, type PreparedLoad } from './dependencies';
import { SpineAssetLoader } from './loaders/SpineAssetLoader';
import { spinePairKey } from './spinePairKey';
import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';
import { MaterialShaderAssetLoader } from './loaders/MaterialShaderAssetLoader';
import { isBuiltinAssetRef } from './documentRef';
import { MeshAssetLoader, type MeshResult } from './loaders/MeshAssetLoader';
import type { MeshData } from './meshFormat';
import { nativeEngineApi, type EngineApi } from '../ecs/bridge/engineApi';
import { isBuiltinMeshRef } from './builtinMeshes';
import { EnvironmentAssetLoader } from './loaders/EnvironmentAssetLoader';
import { ProbeVolumeAssetLoader } from './loaders/ProbeVolumeAssetLoader';
import { MeshSdfAssetLoader } from './loaders/MeshSdfAssetLoader';
import { MeshCardsAssetLoader } from './loaders/MeshCardsAssetLoader';
import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
import { preparePrefabFromSource, type PreparedPrefab } from '../prefab/preparedPrefab';
import type { PrefabOverride } from '../prefab';
import { LocaleAssetLoader } from './loaders/LocaleAssetLoader';
import { JsonAssetLoader } from './loaders/JsonAssetLoader';
import { SoundEventAssetLoader } from './loaders/SoundEventAssetLoader';
import { getComponentDefaults } from '../ecs/component';
import { getComponentAssetFieldDescriptors } from '../scene/scene';
import { discoverSceneAssets } from './discoverAssets';
import { fetchDecodePixels } from './imageDecode';
import type { SceneData, AssetFieldType } from '../scene/scene';
import { SceneHandle, type ReleaseCallback } from './SceneHandle';
import { UUID_REF_PREFIX } from './AssetRegistry';
import type { AssetRefCounter } from './AssetRefCounter';
import { log } from '../util/logger';
import { disposeAll } from '../util/disposeAll';
import { recoverDevice, getDeviceStatus, DeviceStatus } from '../render/renderer';
/**
* One asset generation ending: which ref, what kind of asset it was, and what
* live holders were bound to just before the drop.
*
* The kind travels because every source of one knows it, and a listener that
* has to guess can only serve the kind somebody had in mind.
*/
export interface AssetInvalidation {
/** As the caller spelled it, not the resolved path. */
readonly ref: string;
/** In whichever vocabulary the source knew: a loader/field type, or the
* manifest's type for an applied update. */
readonly type: AssetFieldType | AddressableAssetType;
/** What holders were bound to: a texture's handle, a loader's value.
* Undefined when nothing was cached to report. */
readonly oldValue?: unknown;
}
/** Callback fired when an asset generation ends — `Assets.invalidate(ref)`
* dropped cache entries, or `applyUpdate` replaced the content behind a ref. */
export type InvalidateListener = (event: AssetInvalidation) => void;
/** Input to {@link Assets.checkForUpdate}. */
export interface CheckForUpdateOptions {
/** Url of the candidate (remote) manifest JSON — diffed against the active one. */
manifestUrl: string;
/** CDN root the candidate's `remote`-group assets are served from; remembered
* and applied by {@link Assets.applyUpdate}. Defaults to the current root. */
remoteRoot?: string;
}
/** One asset {@link Assets.applyUpdate} could not deliver: `fetch` (download
* failed) or `integrity` (bytes' content hash ≠ the manifest's). */
export interface AssetDownloadFailure {
path: string;
/** `packed`: the update's manifest packs the asset, and an update downloads assets one by one. */
reason: 'fetch' | 'integrity' | 'packed';
}
/**
* How far an update got. Each is its own answer: an update can be running in this
* session and still be gone on the next launch, which a single `ok` cannot say.
*/
export interface UpdateStages {
/** Every changed asset downloaded and matched its content hash. */
verified: boolean;
/** This session runs on the new manifest, and its asset graph has settled on it. */
applied: boolean;
/** The next launch starts on it: stored, and read back. Null without a persistence key. */
persisted: boolean | null;
/** Every changed remote asset is in the disk cache, so the next launch reads them
* without the network. Null where the platform keeps no cache. */
cached: boolean | null;
}
/** Outcome of {@link Assets.applyUpdate} — atomic: `ok` only when every changed
* asset downloaded + verified and the manifest was swapped. On failure nothing
* is applied (`updated: 0`) and `failed` lists why (rollback). */
export interface ApplyUpdateResult {
ok: boolean;
updated: number;
failed: AssetDownloadFailure[];
stages: UpdateStages;
/** The revision this session runs on afterwards. */
revision: string | null;
/** The changed assets the cache refused, by url: what the next launch fetches again. */
uncached: string[];
/** Why nothing was attempted: no update staged (none checked, or another apply took it). */
reason?: 'nothing-staged';
}
/** What {@link Assets.updateStatus} reports. */
export interface UpdateStatus {
/** The revision this session runs on. */
revision: string | null;
/** The revision the next launch starts on, when an update was persisted. */
persistedRevision: string | null;
/** The update {@link Assets.checkForUpdate} staged, and what applying it downloads. */
staged: { revision: string | null; assets: number; bytes: number } | null;
applying: boolean;
}
/** The manifest + root staged by checkForUpdate, awaiting applyUpdate. */
interface PendingUpdate {
model: ManifestModel;
manifestJson: AddressableManifest;
remoteRoot: string | null;
}
/**
* Default upper bound on concurrent loads inside preloadSceneAssets.
* Picked to match typical browser per-origin connection limits; scenes
* with hundreds of assets would otherwise fan out all at once and
* saturate the network, CPU image decoders, and WASM memory.
*/
const DEFAULT_PRELOAD_CONCURRENCY = 6;
/** A preload's timings are a report, so they need no platform: a realm without
* one (a test, a tool) still loads. */
const preloadClock = (): number => (typeof performance !== 'undefined' ? performance.now() : Date.now());
/**
* Run an array of lazy task thunks with at most `maxConcurrent` in
* flight. Calls `onEach` once per task completion (success or failure)
* so callers can drive a progress indicator. Never rejects — individual
* task errors are expected to be handled inside the thunk itself.
*/
async function runWithConcurrency(
tasks: ReadonlyArray<() => Promise<void>>,
maxConcurrent: number,
onEach: () => void,
): Promise<void> {
if (tasks.length === 0) return;
let cursor = 0;
const workers: Promise<void>[] = [];
const worker = async (): Promise<void> => {
while (cursor < tasks.length) {
const i = cursor++;
try {
await tasks[i]();
} finally {
onEach();
}
}
};
const slots = Math.min(maxConcurrent, tasks.length);
for (let i = 0; i < slots; i++) {
workers.push(worker());
}
await Promise.all(workers);
}
export interface AssetsOptions {
backend: Backend;
catalog?: Catalog;
/**
* Addressable manifest (groups + bundle modes). When set, enables
* `loadGroup(name)`. Accepts the raw manifest JSON or a pre-built
* {@link ManifestModel}. Optional — label/path loading works without it.
*/
manifest?: AddressableManifest | ManifestModel;
/** The wasm module, or null on the native (embedded-Dawn) backend, which has
* no wasm heap — its ResourceManager uploads texture bytes directly. */
module: ESEngineModule | null;
/**
* Lazy accessor for the owning app's Audio API. AudioAssetLoader
* calls it at load time so AssetPlugin and AudioPlugin can be built
* in any order. Pass null (or omit) if no audio support is needed.
*/
getAudio?: () => import('../audio/Audio').AudioAPI | null;
getSpriteAnimation?: () => import('../animation/SpriteAnimator').SpriteAnimationAPI | null;
/** Lazy accessor for the owning app's Localization service, same contract
* as {@link getAudio} — `.eslocale` tables register through it. */
getLocalization?: () => import('../i18n/Localization').LocalizationAPI | null;
}
export interface AssetBundle {
textures: Map<string, TextureResult>;
materials: Map<string, MaterialResult>;
spine: Map<string, SpineResult>;
fonts: Map<string, FontResult>;
/**
* What this load actually acquired. Release through it rather than by group
* name: a manifest can be updated between the two, and then the group's
* membership is no longer the set this bundle took out.
*/
scope: AssetScope;
/** Give back everything this bundle acquired. Idempotent. */
release(): void;
}
function emptyBundle(): AssetBundle {
const scope = new AssetScope();
return {
textures: new Map(), materials: new Map(), spine: new Map(), fonts: new Map(),
scope, release: () => scope.releaseAll(),
};
}
/**
* How one addressable asset type is acquired and given back.
*
* ONE table, because two of them drift: load handled `font` and release did
* not, so every group carrying a font kept its reference forever. A type that
* can be loaded and has no release channel now has to say so out loud.
*/
interface GroupAssetChannel {
load(assets: Assets, path: string, bundle: AssetBundle): Promise<void>;
/** null when something else owns the lifetime — see `spine`. */
release: ((assets: Assets, path: string) => void) | null;
/** In the bundle `loadByLabel` returns: the types a scene can display. */
displayable: boolean;
}
const GROUP_ASSET_CHANNELS: Readonly<Record<string, GroupAssetChannel>> = {
texture: {
load: (a, path, b) => a.acquireTexture(path)
.then((l) => { b.scope.add(l); b.textures.set(path, l.value); }),
release: (a, path) => a.releaseTexture(path),
displayable: true,
},
material: {
load: (a, path, b) => a.acquireTyped<MaterialResult>('material', path)
.then((l) => { b.scope.add(l); b.materials.set(path, l.value); }),
release: (a, path) => a.releaseTyped('material', path),
displayable: true,
},
font: {
load: (a, path, b) => a.acquireTyped<FontResult>('font', path)
.then((l) => { b.scope.add(l); b.fonts.set(path, l.value); }),
release: (a, path) => a.releaseTyped('font', path),
displayable: true,
},
'bitmap-font': {
load: (a, path, b) => a.acquireTyped<FontResult>('font', path)
.then((l) => { b.scope.add(l); b.fonts.set(path, l.value); }),
release: (a, path) => a.releaseTyped('font', path),
displayable: true,
},
spine: {
load: (a, path, b) => a.acquireSpine(path)
.then((l) => { b.scope.add(l); b.spine.set(path, l.value); }),
release: (a, path) => a.releaseTyped('spine', path),
displayable: true,
},
prefab: {
load: (a, path, b) => a.acquireTyped('prefab', path).then((l) => { b.scope.add(l); }),
release: (a, path) => a.releaseTyped('prefab', path),
displayable: false,
},
audio: {
load: (a, path, b) => a.acquireTyped('audio', path).then((l) => { b.scope.add(l); }),
release: (a, path) => a.releaseTyped('audio', path),
displayable: false,
},
};
/**
* Describes one asset a scene / prefab referenced that couldn't be
* materialized into a usable handle. The caller of preloadSceneAssets
* uses this to surface editor UI ("missing asset") or to abort the
* load entirely — instead of the old behaviour of silently storing
* `texture: 0` and hoping the renderer notices.
*/
export interface MissingAsset {
/** The original serialized ref (`"@uuid:..."` or a plain path). */
ref: string;
/** Asset type (`"texture"`, `"material"`, ...) when known. */
type?: string;
/** `unresolved` = UUID not in registry; `load-failed` = fetch threw. */
reason: 'unresolved' | 'load-failed';
/** Stringified error for `load-failed`. */
error?: string;
}
/**
* Say what failed, wherever it failed. Two loading doors reached this same dead
* end — a caller holding an empty result it cannot tell from an empty group —
* so the sentence is written once rather than at each of them.
*/
function warnFailedLoads(failed: readonly MissingAsset[], where?: string): void {
if (failed.length === 0) return;
log.warn('asset', `${where ? `${where}: ` : ''}${failed.length} asset(s) failed to load`, failed);
}
export interface SceneAssetResult {
textureHandles: Map<string, number>;
materialHandles: Map<string, number>;
fontHandles: Map<string, number>;
meshHandles: Map<string, number>;
environmentHandles: Map<string, number>;
probeVolumeHandles: Map<string, number>;
releaseCallbacks: ReleaseCallback[];
/**
* What this preload actually acquired. Release side reads THIS rather than
* re-deriving from the scene's declared refs: a failed load left no lease,
* and an invalidate mid-load left the receipt of the era we really got.
*/
scope: AssetScope;
/** @internal Projection of successful acquisitions; their scope/era remains the owner. */
acquisitions?: readonly { readonly type: string; readonly path: string; readonly lease: AssetLease }[];
missing: MissingAsset[];
/** Per asset type: how many loaded, the sum of their load times and the
* slowest one, in ms. Loads overlap, so the sums exceed the wall time. */
timings: Record<string, { count: number; ms: number; slowestMs: number }>;
/** Wall time of the whole preload, in ms. */
wallMs: number;
}
export type AssetRefResolver = (ref: string) => string | null;
/**
* The asset server: one typed loader per asset type, over one ref vocabulary.
*
* Every `ref` a loader takes is one of two spellings, and both land on the same
* file:
*
* - a **project-root-relative path** — `'assets/textures/player.png'`. Relative
* to the project root, NOT to the assets folder, so it carries the `assets/`
* segment: it is the path the Content Browser shows, the key the cook's
* manifest is built on, and what the backend appends to its base url. A ref
* that drops the root resolves just the same and 404s, because nothing lives
* at the project root.
* - an **`@uuid:` ref** — what the editor serializes into scenes and prefabs so
* renaming or moving the file breaks nothing. Not hand-written; the realm's
* resolver turns it back into the path above before any fetch.
*/
/**
* A path-addressed release had more than one generation to choose from, so it
* took the oldest and may have freed somebody else's asset. Reported once per
* key: the caller that can carry a lease should, and one that cannot needs to
* hear it once, not every frame.
*/
const ambiguousWarned_ = new Set<string>();
function warnAmbiguousRelease_(key: string): void {
if (ambiguousWarned_.has(key)) return;
ambiguousWarned_.add(key);
log.warn('asset',
`release("${key}") had more than one live generation and released the oldest — `
+ 'which may not be the one the caller holds. Release it by its lease instead.');
}
/**
* What edge a mesh texture is first loaded at, asked as each one loads (texture streaming says, by the quality level): set once per
* realm, before any Assets exists, since a scene can load before the first frame. 0 loads it whole.
*/
let textureStreamingStart: () => number = () => 0;
/** @internal */
export function setTextureStreamingStartProvider(provider: () => number): void { textureStreamingStart = provider; }
export class Assets {
readonly backend: Backend;
readonly catalog: Catalog;
get baseUrl(): string | undefined { return this.baseUrl_; }
set baseUrl(url: string | undefined) {
this.baseUrl_ = url;
if (this.backend.setBaseUrl) {
this.backend.setBaseUrl(url ?? '');
}
}
private baseUrl_?: string;
private module_: ESEngineModule | null;
private manifestModel_: ManifestModel | null = null;
/** CDN root that `remote`-group assets resolve against; see {@link setRemoteRoot}. */
private remoteRoot_?: string;
/** Applies run one after another: two at once would each commit, and one that
* finishes after a newer check would clear the newer candidate. */
private applyChain_: Promise<unknown> = Promise.resolve();
private applying_ = 0;
/** The update staged by {@link checkForUpdate}, consumed by {@link applyUpdate}. */
private pendingUpdate_: PendingUpdate | null = null;
/** Storage key {@link applyUpdate} persists the active manifest under; set by
* {@link restorePersistedUpdate}. Null → persistence off. */
private persistKey_: string | null = null;
/** The revision this package shipped, read when persistence is armed at boot. */
private shippedRevision_: string | null = null;
private cacheOwner_: string | null = null;
private cacheRollback_: CacheVersion | null = null;
private cacheLaunch_: CacheVersion | null = null;
private cacheLaunchRollback_: CacheVersion | null = null;
private activeUpdate_: PendingUpdate | null = null;
private getAudio_: () => import('../audio/Audio').AudioAPI | null;
private getSpriteAnimation_: () => import('../animation/SpriteAnimator').SpriteAnimationAPI | null;
private getLocalization_: () => import('../i18n/Localization').LocalizationAPI | null;
private loaders_ = new Map<string, AssetLoader<unknown>>();
private textureLoader_: TextureLoader;
private textureImportResolver_: TextureImportSettingsResolver | null = null;
private spineLoader_: SpineAssetLoader;
private textureCache_ = new AsyncCache<TextureResult>((result) => {
// A texture whose load finished after its getOrLoad timed out has no
// owner; release its GL handle so it doesn't leak VRAM.
requireResourceManager().releaseTexture(result.handle);
});
/** Live texture references per cache key. See {@link AssetRefLedger}. */
private textureRefs_ = new AssetRefLedger<number>();
/**
* Bumped by releaseAll(). A load in flight across one has no owner left: the
* scene that asked is gone and its references were dropped, so the texture
* it produces is destroyed by the pool before the caller's `await` ever
* resumes. Delivering that handle is a use-after-free; the load fails instead.
*/
private resetEpoch_ = 0;
private releasing_ = false;
private preparations_ = new Set<DependencyRecorder>();
/** @internal How many times everything this loader held has been given back: what a holder kept of an earlier one names things that are gone. */
get epoch(): number { return this.resetEpoch_; }
private assertLoading_(epoch = this.resetEpoch_): void {
if (this.releasing_ || epoch !== this.resetEpoch_) {
throw new Error('Assets were released while loading; this request has no owner. Load it again.');
}
}
/** Handles already disowned in this epoch, so N callers sharing one load
* drop its single C++ reference once between them, not N times. */
private abandoned_ = new Set<number>();
private genericCache_ = new Map<string, AsyncCache<PreparedLoad<unknown>>>();
/** Per-asset reference counts for the generic caches, keyed `type:path`.
* Same contract as textures: every load*() increments, every release*()
* decrements, and the loader's unload runs only at zero — so an asset
* shared by two scenes survives the first scene's unload. */
private genericRefs_ = new AssetRefLedger<PreparedLoad<unknown>>();
/** Eras already given back, so N callers abandoning one shared load hand it
* over once between them rather than unloading it N times. */
private retired_ = new WeakSet<PreparedLoad<unknown>>();
/** Propagations in flight — what {@link assetGraphSettled} waits on. */
private settling_ = new Set<Promise<void>>();
private loadContext_: LoadContext | null = null;
private assetRefResolver_: AssetRefResolver | null = null;
private refCounter_: AssetRefCounter | null = null;
private invalidateListeners_ = new Set<InvalidateListener>();
private readonly appScope_ = new AssetScope();
private readonly entityScopes_ = new EntityAssetScopes();
private readonly registrySlots_ = new RegistryAssetSlots();
/** `"<kind>:<handle>"` → resolved load path, recorded on every handle-yielding
* load. The REVERSE of resolution — inspectors and tooling that only hold a
* live World handle use it to name the asset (see {@link pathForHandle}). */
private handleToPath_ = new Map<string, string>();
/** Textures a mesh draws, by resolved path, directly or through a material: what texture streaming may load small to begin with. */
private readonly meshTextures_ = new Set<string>();
/** Materials a mesh draws with, by resolved path: their textures join {@link meshTextures_} as the material loads them. */
private readonly meshMaterials_ = new Set<string>();
/** The edge a mesh texture is first loaded at while texture streaming is on; 0 loads it whole. */
private streamingStartEdge_: number | (() => number) = 0;
/**
* Geometry built at run time rather than loaded (a static batch), by handle. It has no file to be replayed
* from, so the data itself is kept: a device loss puts it back from here.
*/
private builtMeshes_ = new Map<number, MeshData>();
private constructor(options: AssetsOptions) {
this.backend = options.backend && packedBackend(options.backend, () => this.manifestModel_);
this.catalog = options.catalog ?? Catalog.empty();
this.module_ = options.module;
this.getAudio_ = options.getAudio ?? (() => null);
this.getSpriteAnimation_ = options.getSpriteAnimation ?? (() => null);
this.getLocalization_ = options.getLocalization ?? (() => null);
this.setManifest(options.manifest ?? null);
this.textureLoader_ = new TextureLoader(options.module);
this.spineLoader_ = new SpineAssetLoader();
this.registerBuiltinLoaders();
}
static create(options: AssetsOptions): Assets {
return new Assets(options);
}
// =========================================================================
// Loader Registry
// =========================================================================
register<T>(loader: AssetLoader<T>): void {
this.loaders_.set(loader.type, loader as AssetLoader<unknown>);
}
getLoader<T>(type: string): AssetLoader<T> | undefined {
return this.loaders_.get(type) as AssetLoader<T> | undefined;
}
// =========================================================================
// Typed Load Methods (User API)
// =========================================================================
async loadTexture(ref: string): Promise<TextureResult> {
return this.loadTextureVariant_(ref, true);
}
async loadTextureRaw(ref: string): Promise<TextureResult> {
return this.loadTextureVariant_(ref, false);
}
/**
* The textures the engine is waiting for content for — its ledger, not a
* mirror of this cache — with who refills each and the path it was
* registered under. A blank path is not this layer's to fetch.
*/
texturesAwaitingReupload(): { handle: number; content: TextureContent; path: string }[] {
const raw = requireResourceManager().texturesAwaitingReupload?.() ?? '';
if (!raw) return [];
return raw.split('\n').map((line) => {
const [handle, content, ...path] = line.split('|');
return {
handle: Number(handle),
content: Number(content) as TextureContent,
path: path.join('|'),
};
});
}
/**
* Decode the texture behind @p handle again, no larger than @p maxEdge texels on a side (0 is its full size), behind the same handle:
* what texture streaming moves a texture between sizes with. Null for a texture no file of this realm's stands behind.
*/
async resizeTexture(handle: number, maxEdge: number): Promise<{ width: number; height: number } | null> {
const size = await this.textureLoader_.resize(handle, maxEdge, this.getLoadContext_());
if (size) evictTextureDimensions(handle);
return size;
}
/** The size of the file behind @p handle, whatever size it is held at; null for a texture no file of this realm's stands behind. */
textureFullSize(handle: number): { width: number; height: number } | null {
return this.textureLoader_.fullSize(handle);
}
/**
* Load the textures meshes draw no larger than @p edge on a side to begin with (0 loads them whole): texture streaming grows each
* to what its views need. A texture something else also draws is put back at its size by the streamer.
*/
setTextureStreamingStart(edge: number | (() => number)): void {
this.streamingStartEdge_ = edge;
}
/** Whether {@link resizeTexture} can move @p handle between sizes. */
textureResizable(handle: number): boolean {
return this.textureLoader_.resizable(handle);
}
/**
* Refills every owed texture someone can: an asset texture is loaded again and
* moved behind its handle, any other goes to the refill its creator provided.
* Content nobody can remake is forgone by name, or the device recovers forever.
*/
async reuploadTexturesAfterDeviceLoss(): Promise<number> {
const rm = requireResourceManager();
if (!rm.adoptTextureContent) return 0;
let restored = 0;
for (const { handle, content, path } of this.texturesAwaitingReupload()) {
if (content !== TextureContent.Asset || !path) {
const refill = textureRefill(handle);
if (!refill) {
log.warn('assets', `Device recovery: texture ${handle} (${textureContentName(content)})`
+ ' has no provider to refill it; it stays blank');
rm.forgoTextureContent?.(handle);
continue;
}
try {
if (await refill()) restored++;
} catch (e) {
log.warn('assets', `Device recovery: refilling texture ${handle}`
+ ` (${textureContentName(content)}) failed`, e);
}
continue;
}
const cut = path.lastIndexOf(':');
const ref = cut < 0 ? path : path.slice(0, cut);
const flip = cut < 0 || path.slice(cut + 1) === 'f';
try {
const fresh = await this.textureLoader_.loadDetached(
this.resolveLoadPath_(ref), this.getLoadContext_(), flip,
this.textureImportResolver_?.(ref));
if (rm.adoptTextureContent(handle, fresh.handle)) restored++;
rm.releaseTexture(fresh.handle);
} catch (e) {
log.warn('assets', `Device recovery: re-upload failed for ${ref}`, e);
}
}
log.info('assets', `Device recovery: ${restored} texture(s) re-uploaded`);
return restored;
}
/**
* The meshes the engine is waiting for geometry for, by handle. No path
* travels with them: the engine never knew one, and this layer does.
*/
meshesAwaitingRematerialization(): number[] {
const raw = requireResourceManager().meshesAwaitingRemat?.() ?? '';
return raw ? raw.split(',').map(Number).filter((h) => h > 0) : [];
}
/** Every live mesh and whether its geometry is on the device. */
meshRealizations(): { handle: number; realized: boolean }[] {
const raw = requireResourceManager().meshRealizations?.() ?? '';
if (!raw) return [];
return raw.split(',').map((row) => {
const [handle, realized] = row.split(':');
return { handle: Number(handle), realized: realized === '1' };
});
}
/**
* Replays each owed mesh from its source, into the handle it already has.
*
* A missing provenance is a CONTRACT VIOLATION, not a mesh that turns out to
* be unrecoverable: the engine only owes what a producer declared
* replayable, so an absent path means this layer lost the record.
*
* @return How many came back. The rest stay owed.
*/
async rematerializeMeshesAfterDeviceLoss(): Promise<number> {
const loader = this.getLoader<MeshResult>('mesh');
if (!(loader instanceof MeshAssetLoader)) return 0;
let restored = 0;
for (const handle of this.meshesAwaitingRematerialization()) {
const built = this.builtMeshes_.get(handle);
if (built) {
if (loader.uploadData(built, handle) !== 0) restored++;
else log.error('assets', `Device recovery: the engine refused built geometry ${handle}`);
continue;
}
const path = this.pathForHandle('mesh', handle);
if (!path) {
log.error('assets', `Device recovery: mesh ${handle} is declared replayable and`
+ ' has no recorded source — its provenance was lost, so it cannot come back');
continue;
}
try {
if (await loader.rematerialize(handle, path, this.getLoadContext_())) restored++;
else log.error('assets', `Device recovery: the engine refused geometry for ${path}`);
} catch (e) {
log.error('assets', `Device recovery: replaying ${path} failed`, e);
}
}
log.info('assets', `Device recovery: ${restored} mesh(es) rematerialized`);
return restored;
}
/**
* Pays what the engine owes after rebuilding the device. The rebuild itself
* is the engine's, once per loss; this only refills content. Returns whether
* the device is whole — false while the context is not back yet, or while
* content is still owed, so a caller retries.
*/
async recoverFromDeviceLoss(): Promise<boolean> {
if (!recoverDevice()) return false;
await this.reuploadTexturesAfterDeviceLoss();
await this.rematerializeMeshesAfterDeviceLoss();
const whole = getDeviceStatus() === DeviceStatus.Live;
if (!whole) {
const owed = this.texturesAwaitingReupload().length + this.meshesAwaitingRematerialization().length;
log.warn('assets', `Device recovery: ${owed} texture(s)/mesh(es) have not come back`);
}
return whole;
}
/** The decoded geometry behind a mesh handle this realm loaded, or null when nothing here can name it. */
async readMeshData(handle: number): Promise<MeshData | null> {
const loader = this.getLoader<MeshResult>('mesh');
const path = this.pathForHandle('mesh', handle);
if (!(loader instanceof MeshAssetLoader) || !path) return null;
try {
return await loader.readSource(path, this.getLoadContext_());
} catch (e) {
log.warn('assets', `Reading the geometry of ${path} failed`, e);
return null;
}
}
/** Uploads geometry built at run time. Returns its handle, or 0 when the engine refused it. */
createMesh(data: MeshData): number {
const loader = this.getLoader<MeshResult>('mesh');
if (!(loader instanceof MeshAssetLoader)) return 0;
const handle = loader.uploadData(data);
if (handle !== 0) this.builtMeshes_.set(handle, data);
return handle;
}
/** Gives back geometry {@link createMesh} made. */
releaseBuiltMesh(handle: number): void {
if (!this.builtMeshes_.delete(handle)) return;
const loader = this.getLoader<MeshResult>('mesh');
if (loader instanceof MeshAssetLoader) loader.releaseData(handle);
}
private async loadTextureVariant_(ref: string, flip: boolean): Promise<TextureResult> {
return (await this.acquireTextureVariant_(ref, flip)).result;
}
private async acquireTextureVariant_(
ref: string, flip: boolean,
): Promise<{ result: TextureResult; lease: AssetRefLease<number> }> {
this.assertLoading_();
const path = this.resolveLoadPath_(ref);
const cacheKey = this.textureCacheKey_(path, flip);
const settings = this.textureImportResolver_?.(ref);
const epoch = this.resetEpoch_;
const result = await this.textureCache_.getOrLoad(cacheKey, () => {
// Warm-cache hit: a texture whose last reference was released stays
// resident in the C++ pool (up to the texture budget) under this
// exact key — reviving it skips the whole fetch + decode + upload.
const revived = this.reviveResidentTexture_(cacheKey);
if (revived) return Promise.resolve(revived);
this.textureLoader_.setPendingSettings(settings);
// Asked as each texture loads: what decides it (the quality level) may arrive after whoever said how to ask.
const own = typeof this.streamingStartEdge_ === 'function' ? this.streamingStartEdge_() : this.streamingStartEdge_;
const start = own > 0 ? own : textureStreamingStart();
if (start > 0 && this.meshTextures_.has(path)) this.textureLoader_.setPendingStartEdge(start);
return flip
? this.textureLoader_.load(path, this.getLoadContext_())
: this.textureLoader_.loadRaw(path, this.getLoadContext_());
});
// BEFORE acquiring, so no ledger entry is ever created for a load nobody
// is left to own — one that N shared callers would each then drop,
// releasing the load's single C++ reference N times.
if (epoch !== this.resetEpoch_) {
if (!this.abandoned_.has(result.handle)) {
this.abandoned_.add(result.handle);
requireResourceManager().releaseTexture(result.handle);
evictTextureDimensions(result.handle);
}
throw new Error(
`Assets were released while "${ref}" was loading; its texture has no owner. Load it again.`,
);
}
const lease = this.textureRefs_.acquire(cacheKey, result.handle);
this.recordHandlePath_('texture', result.handle, path);
// The 9-slice border belongs to the IMAGE, so it rides its import
// settings and is stamped onto the handle here — the one place every
// creation path (decode, revive, external, cooked) funnels through, and
// where the settings are already resolved. Without this a UIVisual set
// to NineSlice finds no texture metadata and stretches its corners.
if (settings?.sliceBorder) {
const b = settings.sliceBorder;
requireResourceManager().setTextureMetadata(result.handle, b.left, b.right, b.top, b.bottom);
}
return { result, lease };
}
/**
* Try to revive an evictable texture from the C++ pool's residency cache.
* Returns null on a miss — or when the resource-manager surface doesn't
* support residency (minimal test mocks). Gated on invalidateTexturePath
* too: reviving without the ability to sever a path on hot reload could
* hand out stale bytes, so both must be present or neither is used.
*/
private reviveResidentTexture_(cacheKey: string): TextureResult | null {
const rm = requireResourceManager();
if (typeof rm.acquireTextureByPath !== 'function'
|| typeof rm.invalidateTexturePath !== 'function') return null;
const handle = rm.acquireTextureByPath(cacheKey);
if (!handle) return null;
const dims = rm.getTextureDimensions(handle);
if (!dims) {
rm.releaseTexture(handle);
return null;
}
this.textureLoader_.adoptRevived(handle, cacheKey);
return { handle, width: dims.width, height: dims.height };
}
/**
* Provide per-asset texture import settings at load time (filter, wrap,
* mipmaps). The resolver is called with the original ref — keyed off
* `@uuid:...` in editor scenarios. Returning `undefined` uses defaults.
*/
setTextureImportSettingsResolver(resolver: TextureImportSettingsResolver | null): void {
this.textureImportResolver_ = resolver;
}
getTexture(ref: string): TextureResult | undefined {
const path = this.resolveLoadPath_(ref);
return this.textureCache_.get(this.textureCacheKey_(path, true));
}
/**
* The load path behind a LIVE handle (`kind` = the asset slot type:
* 'texture' | 'material' | 'font' | …), or null when this realm never
* loaded such a handle. The reverse of ref resolution — the live "Game"
* inspector uses it to show WHICH asset a World component's handle-valued
* slot is wearing (a raw handle number names nothing to a human).
*/
pathForHandle(kind: string, handle: number): string | null {
return this.handleToPath_.get(`${kind}:${handle}`) ?? null;
}
/**
* The load path of a texture by the id the renderer bound it with — a frame
* capture's `textureId` — rather than by asset handle. Null for a texture no
* asset of this realm loaded: the white fill, a render target, a glyph atlas.
*/
pathForRenderedTexture(renderId: number): string | null {
const rm = getResourceManager();
if (!rm || renderId === 0) return null;
for (const [key, path] of this.handleToPath_) {
if (key.startsWith('texture:') && rm.getTextureGLId(Number(key.slice('texture:'.length))) === renderId) {
return path;
}
}
return null;
}
/** Record a handle→path pair, dropped on invalidation or final release. */
private recordHandlePath_(kind: string, handle: number, path: string): void {
if (handle !== 0) this.handleToPath_.set(`${kind}:${handle}`, path);
}
/** {@link acquireSpine} without the receipt, for a caller that will let the
* realm's teardown be its release. */
async loadSpine(skeletonRef: string, atlasRef?: string): Promise<SpineResult> {
return (await this.acquireSpine(skeletonRef, atlasRef)).value;
}
/**
* One spine PAIR — a skeleton and the atlas it is drawn with. The same
* skeleton with another atlas is another asset, which is why the receipt
* names the pair and not the skeleton's path.
*/
async acquireSpine(skeletonRef: string, atlasRef?: string): Promise<AssetLease<SpineResult>> {
try { return await this.acquireSpineLease_(skeletonRef, atlasRef); }
catch (error) { throw preparationFailureReason(error); }
}
private async acquireSpineLease_(skeletonRef: string, atlasRef?: string): Promise<AssetLease<SpineResult>> {
const skeleton = this.resolveLoadPath_(skeletonRef);
const atlas = this.spineAtlasOf_(skeleton, atlasRef);
const key = spinePairKey(skeleton, atlas);
const { value, lease } = await this.acquirePrepared_<SpineResult>(
'spine', key, skeletonRef,
(ctx) => this.spineLoader_.prepare(skeleton, atlas, ctx),
);
return this.typedLease_('spine', lease, value);
}
/** The atlas of a pair the caller named only half of: a skeleton's atlas is
* a Catalog dependency, which is what a cook records for it. */
private spineAtlasOf_(skeleton: string, atlasRef?: string): string {
if (atlasRef) return this.resolveLoadPath_(atlasRef);
const deps = this.catalog.getDeps(skeleton);
if (deps.length === 0) {
throw new Error(`Spine skeleton has no atlas dependency: ${skeleton}. `
+ 'Pass the atlas explicitly or configure Catalog deps.');
}
return deps[0];
}
async loadMaterial(ref: string): Promise<MaterialResult> {
return this.loadTyped('material', ref);
}
async loadFont(ref: string): Promise<FontResult> {
return this.loadTyped('font', ref);
}
async loadAudio(ref: string): Promise<AudioResult> {
return this.loadTyped('audio', ref);
}
async loadAnimClip(ref: string): Promise<AnimClipResult> {
return (await this.acquireAnimClip_(ref)).value;
}
/**
* A clip is published under the load path AND the ref as it was spelled: a
* realm whose resolver returns URLs hands the loader `estella://…/walk.esanim`
* while components ask for `assets/animations/walk.esanim`. Both names are
* the slot's, so a republish is seen through either.
*/
private async acquireAnimClip_(ref: string): Promise<AssetLease<AnimClipResult>> {
return this.acquireTyped<AnimClipResult>('anim-clip', ref);
}
async loadTilemap(ref: string): Promise<TilemapResult> {
return this.loadTyped('tilemap', ref);
}
async loadTileset(ref: string): Promise<TilesetResult> {
return this.loadTyped('tileset', ref);
}
async loadTimeline(ref: string): Promise<TimelineResult> {
return this.loadTyped('timeline', ref);
}
/** Load a `.eslocale` string table and merge it into the app's Localization
* catalogs. Requires the LocalizationPlugin (fails loud otherwise). */
async loadLocaleTable(ref: string): Promise<LocaleResult> {
return this.loadTyped('locale', ref);
}
/** Load a `.esfsm` state machine into the shared AI store, keyed by its
* asset path — the ref a StateMachineAgent's `fsm` field resolves. */
async loadStateMachine(ref: string): Promise<FsmResult> {
return this.loadTyped('statemachine', ref);
}
/** Load a `.esbt` behavior tree into the shared AI store, keyed by its
* asset path — the ref a BehaviorTreeAgent's `bt` field resolves. */
async loadBehaviorTree(ref: string): Promise<BtResult> {
return this.loadTyped('behaviortree', ref);
}
/** Load a `.esanimator` controller into the shared animator store, keyed by
* its asset path — the ref an Animator's `controller` field resolves. */
async loadAnimatorController(ref: string): Promise<AnimatorControllerResult> {
return this.loadTyped('animatorcontroller', ref);
}
async loadPrefab(ref: string): Promise<PrefabResult> {
return this.loadTyped('prefab', ref);
}
/**
* Load a `.json` data asset — a game's own table, tuning or dialogue file.
*
* `T` is what the caller expects the document to be; nothing validates it,
* so this is `JSON.parse`'s guarantee, not a schema's. What the asset system
* adds over fetching the file yourself is everything around the parse: ref
* resolution (`@uuid:` and manifest paths), one parse per file, group /
* subpackage delivery, and hot update.
*/
async loadJson<T = unknown>(ref: string): Promise<JsonResult<T>> {
return this.loadTyped('json', ref);
}
// =========================================================================
// Generic Load (for custom loaders)
// =========================================================================
async load<T>(type: string, ref: string): Promise<T> {
return this.loadTyped<T>(type, ref);
}
// =========================================================================
// Atlas Query
// =========================================================================
getAtlasFrame(ref: string): AtlasFrameInfo | null {
// Raw ref first: atlas frames register under every ref SPELLING
// (`@uuid:…`, logical, "/"-rooted). The resolved path is the fallback —
// for packed frames it is the shared PAGE path, which cannot key
// per-frame data.
return this.catalog.getAtlasFrame(ref)
?? this.catalog.getAtlasFrame(this.resolveLoadPath_(ref));
}
// =========================================================================
// Addressable Manifest (groups / bundle modes)
// =========================================================================
/**
* Set (or clear) the addressable manifest used by {@link loadGroup}.
* Accepts the raw manifest JSON or a pre-built {@link ManifestModel};
* `null` clears it.
*/
setManifest(manifest: AddressableManifest | ManifestModel | null): void {
this.manifestModel_ =
manifest == null ? null
: manifest instanceof ManifestModel ? manifest
: ManifestModel.fromJson(manifest);
}
getManifest(): ManifestModel | null {
return this.manifestModel_;
}
// =========================================================================
// Batch Load (by label / by group)
// =========================================================================
async loadByLabel(
label: string,
onProgress?: (loaded: number, total: number) => void,
): Promise<AssetBundle> {
const bundle = emptyBundle();
let loadedCount = 0;
const promises: Promise<void>[] = [];
const track = (p: Promise<void>): Promise<void> =>
p.then(() => { onProgress?.(++loadedCount, totalCount); })
.catch(() => { onProgress?.(++loadedCount, totalCount); });
for (const path of this.catalog.getByLabel(label)) {
const entry = this.catalog.getEntry(path);
if (!entry) continue;
const task = this.bundleLoadTask_(path, entry.type, bundle);
if (task) promises.push(track(task));
}
const totalCount = promises.length;
onProgress?.(0, totalCount);
loadedCount = 0;
await Promise.allSettled(promises);
return bundle;
}
/**
* Load every asset in an addressable group through the typed loaders,
* warming the cache (and populating the returned bundle for the four
* displayable types). Requires a manifest (see {@link setManifest}); with
* no manifest set, this is a no-op returning an empty bundle.
*
* This is the single group-loading channel — the basis for on-demand /
* subpackage delivery. It dispatches through the same per-type loaders as
* {@link loadByLabel}, so the two never diverge.
*/
async loadGroup(
groupName: string,
onProgress?: (loaded: number, total: number) => void,
): Promise<AssetBundle> {
const bundle = emptyBundle();
const model = this.manifestModel_;
if (!model) {
log.warn('asset', `loadGroup('${groupName}') called but no manifest is set`);
onProgress?.(0, 0);
return bundle;
}
const mode = model.bundleMode(groupName);
// A lazy group is an on-demand subpackage — download it before loading its
// assets (no-op on platforms without a subpackage concept, e.g. web).
if (mode === 'lazy') {
await platformLoadSubpackage(groupName);
}
let loadedCount = 0;
const promises: Promise<void>[] = [];
// A subpackage that downloads but stages nothing reads exactly like a
// group that was always empty, so the failures are named, not counted.
const failed: MissingAsset[] = [];
const track = (p: Promise<void>, ref: string, type: string): Promise<void> =>
p.then(() => { onProgress?.(++loadedCount, totalCount); })
.catch((e: unknown) => {
failed.push({ ref, type, reason: 'load-failed', error: String(e) });
onProgress?.(++loadedCount, totalCount);
});
for (const asset of model.assetsInGroup(groupName)) {
const path = this.manifestAssetUrl_(asset.path, mode === 'remote');
const task = this.groupLoadTask_(path, asset.type, bundle);
if (task) promises.push(track(task, path, asset.type));
}
const totalCount = promises.length;
onProgress?.(0, totalCount);
loadedCount = 0;
await Promise.allSettled(promises);
warnFailedLoads(failed, `loadGroup('${groupName}')`);
return bundle;
}
/**
* Release every asset the group's CURRENT membership names.
*
* @details Prefer `bundle.release()` on what {@link loadGroup} returned:
* this door re-reads the manifest, so an update between the two
* releases a set the load never took. No-op without a manifest.
*/
releaseGroup(groupName: string): void {
const model = this.manifestModel_;
if (!model) {
log.warn('asset', `releaseGroup('${groupName}') called but no manifest is set`);
return;
}
const mode = model.bundleMode(groupName);
for (const asset of model.assetsInGroup(groupName)) {
// The SAME path loadGroup acquired under. Resolving it a different
// way here would release a key nobody holds, which is a leak that
// looks exactly like a working release.
const path = this.manifestAssetUrl_(asset.path, mode === 'remote');
GROUP_ASSET_CHANNELS[asset.type]?.release?.(this, path);
}
}
// =========================================================================
// Hot Update (content-addressed remote delivery)
// =========================================================================
/** The CDN / remote root that `remote`-group assets resolve against. */
get remoteRoot(): string | undefined { return this.remoteRoot_; }
/** Point `remote`-group resolution at a CDN root: their content-addressed
* paths then fetch from `<root>/<path>`. A trailing slash is trimmed;
* `undefined` clears it (same-origin fallback). */
setRemoteRoot(url: string | undefined): void {
this.remoteRoot_ = url ? url.replace(/\/+$/, '') : undefined;
}
/** Absolute url of a `remote`-group asset against `root` (default the active
* remote root). An already-absolute manifest path (a fully-qualified CDN url)
* passes through; with no root the path returns as-is (same-origin fallback). */
private remoteUrlFor_(path: string, root: string | undefined = this.remoteRoot_): string {
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) return path;
if (!root) return path;
return `${root.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
}
/** The load url for a manifest asset. A `remote`-group asset resolves to its
* `<root>/<path>` CDN url when a root is set; every other case (local / lazy
* group, or a remote group with no CDN root — same-origin realms like editor
* Play) resolves through the normal resolver + Catalog. The single remote/local
* routing rule shared by {@link loadGroup} and {@link fetchAndVerify_}, so a
* loadGroup'd asset and the same asset reached by a scene `@uuid` ref (via
* {@link resolveLoadPath_} → {@link remoteAssetPath_}) never resolve two ways. */
private manifestAssetUrl_(path: string, isRemote: boolean, root: string | undefined = this.remoteRoot_): string {
return isRemote && root ? this.remoteUrlFor_(path, root) : this.resolveLoadPath_(path);
}
/**
* Fetch a candidate manifest and diff it against the active one WITHOUT
* applying anything — the "is there an update, and how big?" query. The
* returned plan (changed assets + byte total) is what a UI shows before
* asking the player to download; the candidate is staged for {@link applyUpdate}.
*
* Diffing is by content hash (see {@link diffManifests}); because assets are
* content-addressed, a changed asset is a brand-new url, so applying can never
* overwrite or corrupt a cached file.
*/
async checkForUpdate(options: CheckForUpdateOptions): Promise<UpdatePlan> {
const text = await this.backend.fetchText(this.backend.resolveUrl(options.manifestUrl));
const json = JSON.parse(text) as AddressableManifest;
const model = ManifestModel.fromJson(json);
const plan = diffManifests(this.manifestModel_, model);
const remoteRoot = options.remoteRoot ?? this.remoteRoot_ ?? null;
this.pendingUpdate_ = { model, manifestJson: json, remoteRoot };
await this.protectCacheVersions_();
return plan;
}
/**
* Apply the update staged by the last {@link checkForUpdate}, ATOMICALLY.
* Phase 1 downloads AND integrity-verifies every changed (content-addressed)
* asset — bytes are hashed and checked against the manifest's `contentHash`,
* so a corrupted / tampered CDN response is caught. Only if ALL succeed does
* phase 2 commit: swap the active manifest + root, rebind live handles (via
* `onInvalidate`), and persist. If any asset fails to download or fails its
* hash check, NOTHING is swapped — the old manifest stays active (rollback)
* and the failures are returned. No-op with nothing staged.
*/
async applyUpdate(onProgress?: (loaded: number, total: number) => void): Promise<ApplyUpdateResult> {
this.applying_++;
const run = this.applyChain_.then(async () => {
try { return await this.applyStaged_(onProgress); }
finally { this.activeUpdate_ = null; }
});
this.applyChain_ = run.catch(() => {});
try {
return await run;
} finally {
this.applying_--;
}
}
private async applyStaged_(onProgress?: (loaded: number, total: number) => void): Promise<ApplyUpdateResult> {
const pending = this.pendingUpdate_;
const revision = (): string | null => this.manifestModel_?.revision() ?? null;
const none: UpdateStages = { verified: false, applied: false, persisted: false, cached: false };
if (!pending) {
log.warn('asset', 'applyUpdate() called with no pending update — call checkForUpdate first');
onProgress?.(0, 0);
return { ok: false, updated: 0, failed: [], stages: none, revision: revision(), uncached: [], reason: 'nothing-staged' };
}
// Against what runs NOW, not what ran when it was checked: an apply that
// finished in between moved the base, and its assets need no second download.
const changed = diffManifests(this.manifestModel_, pending.model).changedAssets;
const root = pending.remoteRoot ?? undefined;
this.activeUpdate_ = pending;
await this.protectCacheVersions_();
// Phase 1 — download + verify EVERY changed asset WITHOUT touching the
// active manifest. Content-addressed, so these are brand-new urls (nothing
// is overwritten); any failure here leaves the old manifest active = rollback.
const failed: AssetDownloadFailure[] = [];
const uncached: string[] = [];
let cacheable = false;
let done = 0;
onProgress?.(0, changed.length);
const tasks = changed.map((c) => async (): Promise<void> => {
const got = await this.fetchAndVerify_(c, pending.model, root);
if (got.failure) failed.push({ path: c.path, reason: got.failure });
if (got.cache !== 'unsupported' && got.cache !== undefined) cacheable = true;
if (got.cache === 'failed') uncached.push(got.url);
});
await runWithConcurrency(tasks, DEFAULT_PRELOAD_CONCURRENCY, () => {
onProgress?.(++done, changed.length);
});
if (failed.length > 0) {
log.warn('asset', `applyUpdate: ${failed.length}/${changed.length} asset(s) failed — update rolled back (manifest unchanged)`);
return { ok: false, updated: 0, failed, stages: none, revision: revision(), uncached: [] };
}
// Phase 2 — commit atomically. Capture the texture handle bound to each
// changed asset BEFORE the swap (it resolves to the OLD path), then swap
// root + manifest and notify with that handle so the built-in rebinder
// swaps it to the freshly-fetched content in live components.
const oldHandles = new Map<string, number>();
for (const c of changed) {
// A manifest names an asset by its bare key and a scene serializes it as
// `@uuid:<key>`; the two resolve down different routes. Ask both, or the
// handle a scene is holding is invisible from here.
const tex = this.getTexture(c.key) ?? this.getTexture(`${UUID_REF_PREFIX}${c.key}`);
if (tex) oldHandles.set(c.key, tex.handle);
}
const rollback = this.cacheVersion_(this.manifestModel_, this.remoteRoot_, 'rollback');
// Protect both sides durably BEFORE committing: a crash may still boot
// the old persisted manifest until the new one has been stored.
const previousRollback = this.cacheRollback_;
this.cacheRollback_ = rollback;
try {
await this.protectCacheVersions_(this.cacheVersion_(pending.model, root, 'current'));
} catch (err) {
this.cacheRollback_ = previousRollback;
throw err;
}
if (pending.remoteRoot != null) this.setRemoteRoot(pending.remoteRoot);
this.setManifest(pending.model);
// A newer check staged while this one downloaded stays staged.
if (this.pendingUpdate_ === pending) this.pendingUpdate_ = null;
// The manifest record already says what kind each changed asset is; the
// notification carries it rather than collapsing to "maybe a texture".
// Changing content and rebinding nothing had no words: every holder keeps
// the old pixels while the caller is told `applied: true, failed: 0`. With
// the keys, because a key the cache never saw is what that looks like.
if (changed.length > 0 && oldHandles.size === 0) {
log.warn('asset', 'applyUpdate: no changed asset is bound to a live texture, so this'
+ ` update will rebind nothing. ${changed.map((c) => `${c.type} ${c.key}`
+ ` -> ${this.resolveLoadPath_(c.key)}`).join('; ')}`);
}
for (const c of changed) this.fireInvalidate_({ ref: c.key, type: c.type, oldValue: oldHandles.get(c.key) });
// A changed asset is content-addressed, so its next load finds the update
// on its own. An era already BUILT from one cannot: it holds what it read
// at the revision it was prepared in, and only the walk ends it.
for (const c of changed) {
// Read the plan before anything is re-prepared, then the changed
// asset's own slot: it is keyed by its identity, so the update
// reaches it by preparing an era from the new revision's locator.
const plan = this.rebuildPlan_(c.key);
this.track_(this.republishSlots_(c.key).rebuilt.then(() => this.rebuildAssetGraph_(plan)));
}
// The update is applied when the asset graph agrees with the manifest —
// not when the manifest was swapped. Bindings converge on a frame, which
// an app that is not ticking would never reach from here.
await this.assetGraphSettled();
const persisted = this.persistActiveManifest_(pending.manifestJson);
// Until storage accepts the new manifest, the previous next-launch
// version AND its rollback must remain pinned across subsequent updates.
if (persisted === true) {
this.cacheLaunch_ = this.cacheVersion_(pending.model, root, 'retained');
this.cacheLaunchRollback_ = rollback ? { ...rollback, reason: 'retained' } : null;
}
await this.protectCacheVersions_().catch(e => log.warn('asset', 'updated content is protected but its cache index could not be refreshed', e));
if (persisted !== true) {
log.warn('asset', persisted === false
? 'applyUpdate: the update runs now, but was not stored — the next launch starts on the previous version'
: 'applyUpdate: no persistence key (restorePersistedUpdate was never called), so the next launch starts on what shipped');
}
return {
ok: true, updated: changed.length, failed: [], revision: revision(), uncached,
stages: { verified: true, applied: true, persisted, cached: cacheable ? uncached.length === 0 : null },
};
}
/** Which revision runs, which one the next launch starts on, and what is staged. */
updateStatus(): UpdateStatus {
const pending = this.pendingUpdate_;
const changed = pending ? diffManifests(this.manifestModel_, pending.model).changedAssets : [];
return {
revision: this.manifestModel_?.revision() ?? null,
persistedRevision: this.persistedRevision_(),
staged: pending ? {
revision: pending.model.revision(), assets: changed.length,
bytes: changed.reduce((n, c) => n + c.size, 0),
} : null,
applying: this.applying_ > 0,
};
}
private cacheVersion_(model: ManifestModel | null, root: string | undefined, reason: CacheVersion['reason']): CacheVersion | null {
if (!model) return null;
const keys = model.entries().filter(e => normalizeBundleMode(model.group(e.group)?.bundleMode) === 'remote')
.map(e => this.backend.resolveUrl(this.manifestAssetUrl_(e.asset.path, true, root)))
// A remote group with no CDN root is shipped in the package. Its
// files need no cache protection and are not missing offline bytes.
.filter(key => /^https?:\/\//i.test(key));
return { revision: model.revision() ?? contentHashHex(encodeUtf8(JSON.stringify(keys))), reason, keys };
}
private async protectCacheVersions_(current?: CacheVersion | null): Promise<void> {
if (!isPlatformInitialized()) return;
const cache = contentCacheFor(getPlatform());
if (cache.capability() !== 'managed') return;
this.cacheOwner_ ??= `assets:${this.persistKey_ ?? this.remoteRoot_ ?? 'package'}`;
this.cacheLaunch_ ??= this.cacheVersion_(this.manifestModel_, this.remoteRoot_, 'retained');
const versions = [current ?? this.cacheVersion_(this.manifestModel_, this.remoteRoot_, 'current'),
this.cacheRollback_, this.cacheLaunch_, this.cacheLaunchRollback_];
for (const update of [this.pendingUpdate_, this.activeUpdate_]) if (update) {
versions.push(this.cacheVersion_(update.model, update.remoteRoot ?? undefined, 'pending'));
}
await cache.protect(this.cacheOwner_, versions.filter((v): v is CacheVersion => v !== null));
}
/** Disk cache statistics, distinct from texture/audio residency budgets.
* A scan reconciles interrupted writes/deletes; unknown files stay pinned. */
async diskCacheReport(rescan = false): Promise<ContentCacheReport> {
if (!isPlatformInitialized()) return { capability: 'unavailable', usedBytes: null, indexBytes: null,
protectedBytes: null, reclaimableBytes: null, entries: [], versions: [] };
// Keep in-memory protection even at quota: requiring an index write
// before showing/cleaning a full disk would make it impossible to free.
await this.protectCacheVersions_().catch(e => log.warn('asset', 'cache protection is active but its index could not be stored', e));
return { ...await contentCacheFor(getPlatform()).report(rescan), owner: this.cacheOwner_ ?? undefined };
}
/** Preview by default; execution recomputes LRU against current protections. */
async cleanDiskCache(budgetBytes: number, execute = false): Promise<CacheCleanupResult> {
if (!Number.isSafeInteger(budgetBytes) || budgetBytes < 0) throw Error('cache budget must be a non-negative safe integer');
await this.diskCacheReport();
if (!isPlatformInitialized()) return { report: await this.diskCacheReport(), budgetBytes,
candidates: [], releaseBytes: 0, remainingBytes: null, budgetMet: null, removed: [], failed: [] };
const result = await contentCacheFor(getPlatform()).cleanup(budgetBytes, execute);
result.report.owner = this.cacheOwner_ ?? undefined;
return result;
}
/** Keep an older downloaded build, independently of the rolling rollback. */
async retainDiskCacheVersion(revision: string, retain = true): Promise<ContentCacheReport> {
await this.diskCacheReport();
if (!isPlatformInitialized() || !this.cacheOwner_) throw Error('cache management unavailable');
const cache = contentCacheFor(getPlatform());
await cache.retainVersion(this.cacheOwner_, revision, retain);
return { ...await cache.report(), owner: this.cacheOwner_ };
}
/** Download one changed asset's bytes from its delivery source (remote → CDN
* url against `root`, else the normal resolved path) and verify the content
* hash. Null on success, else the failure reason. Uses the PENDING manifest +
* root — phase 1 runs before the swap. */
private async fetchAndVerify_(
c: AssetChange, model: ManifestModel, root: string | undefined,
): Promise<{ url: string; failure?: AssetDownloadFailure['reason']; cache?: 'stored' | 'failed' | 'unsupported' }> {
const group = model.group(c.group);
const remote = group != null && normalizeBundleMode(group.bundleMode) === 'remote';
// An export with hot update configured does not pack; a manifest that does
// was built for a package that is not updated, and is refused rather than
// fetched as files that do not exist.
if (model.packOf(c.path)) return { url: c.path, failure: 'packed' };
const path = this.manifestAssetUrl_(c.path, remote, root);
const url = this.backend.resolveUrl(path);
try {
const buf = await this.backend.fetchBinary(url);
if (c.contentHash && contentHashHex(new Uint8Array(buf)) !== c.contentHash) {
return { url, failure: 'integrity' };
}
// Verified, content-addressed bytes go to the disk cache keyed by the
// immutable CDN url, so the next launch reads them offline. A refused
// write does not fail the update; it is reported as not cached.
return { url, cache: remote ? await platformWriteCacheFile(url, buf) : undefined };
} catch {
return { url, failure: 'fetch' };
}
}
/**
* Remember a storage key under which {@link applyUpdate} persists the active
* manifest, and immediately restore any manifest a prior run persisted there —
* so a returning player boots straight onto the updated content, even offline.
* Returns true if a persisted manifest was found and made active. Call at
* boot, before the first scene loads.
*/
restorePersistedUpdate(key: string): boolean {
this.persistKey_ = key;
// What this package shipped: an update stored against any other package is
// older than what the player now has installed.
this.shippedRevision_ = this.manifestModel_?.revision() ?? null;
const raw = platformGetStorageItem(key);
if (!raw) return false;
try {
const parsed = JSON.parse(raw) as { manifest: AddressableManifest; remoteRoot?: string | null; base?: string | null; cacheRollback?: CacheVersion | null };
if (parsed.base === undefined || parsed.base !== this.shippedRevision_) {
log.info('asset', `a stored update (${parsed.manifest?.revision ?? '?'}) was made for another package `
+ `(${parsed.base ?? 'unknown'}, this one ships ${this.shippedRevision_ ?? 'none'}) — starting on what shipped`);
platformRemoveStorageItem(key);
return false;
}
if (parsed.remoteRoot) this.setRemoteRoot(parsed.remoteRoot);
this.setManifest(parsed.manifest);
if (parsed.cacheRollback && typeof parsed.cacheRollback.revision === 'string'
&& Array.isArray(parsed.cacheRollback.keys) && parsed.cacheRollback.keys.every(k => typeof k === 'string')) {
this.cacheRollback_ = { ...parsed.cacheRollback, reason: 'rollback' };
this.cacheLaunchRollback_ = { ...this.cacheRollback_, reason: 'retained' };
}
void this.protectCacheVersions_().catch(e => log.warn('asset', 'cache protection could not be persisted', e));
return true;
} catch (e) {
log.warn('asset', 'failed to restore persisted manifest', e);
return false;
}
}
/** True once stored and read back; a store can drop a write without throwing.
* Null with no persistence key. */
private persistActiveManifest_(json: AddressableManifest): boolean | null {
if (!this.persistKey_) return null;
const value = JSON.stringify({ manifest: json, remoteRoot: this.remoteRoot_ ?? null, base: this.shippedRevision_, cacheRollback: this.cacheRollback_ });
try {
platformSetStorageItem(this.persistKey_, value);
return platformGetStorageItem(this.persistKey_) === value;
} catch (e) {
log.warn('asset', 'failed to persist updated manifest', e);
return false;
}
}
private persistedRevision_(): string | null {
const raw = this.persistKey_ ? platformGetStorageItem(this.persistKey_) : null;
if (!raw) return null;
try {
return (JSON.parse(raw) as { manifest?: AddressableManifest }).manifest?.revision ?? null;
} catch {
return null;
}
}
/**
* Load one asset into the displayable bundle maps. Returns the in-flight
* promise for the four bundle-able types (texture / material / spine /
* font), or null for any other type. Shared by `loadByLabel` and
* `loadGroup` so both dispatch through one channel.
*/
private bundleLoadTask_(
path: string, type: string, bundle: AssetBundle,
): Promise<void> | null {
const channel = GROUP_ASSET_CHANNELS[type];
if (!channel?.displayable) return null;
return channel.load(this, path, bundle);
}
/**
* Like {@link bundleLoadTask_} but also warms the cache for non-displayable
* types that have a typed loader (prefab, audio), so a whole group / sub-
* package preloads. Raw types (json / text / binary) and unknowns return
* null — they have no typed loader and are fetched lazily on demand.
*/
private groupLoadTask_(
path: string, type: string, bundle: AssetBundle,
): Promise<void> | null {
const channel = GROUP_ASSET_CHANNELS[type];
return channel ? channel.load(this, path, bundle) : null;
}
/**
* Preload an explicit list of refs (`@uuid:` or paths) through the typed
* loaders, warming every cache with bounded concurrency and progress.
* This is the streaming prefetch primitive: point it at the next area's
* assets while gameplay continues, and the eventual real loads hit warm
* caches (or revive resident textures) instead of the network.
*
* Asset types come from the catalog / manifest when known, falling back
* to file-extension matching against the registered loaders. Refs whose
* type can't be determined — and refs that fail to load — are reported
* in `failed`; preload itself never rejects.
*/
async preload(
refs: ReadonlyArray<string>,
onProgress?: (loaded: number, total: number) => void,
options?: { readonly maxConcurrent?: number },
): Promise<{ failed: MissingAsset[] }> {
const failed: MissingAsset[] = [];
const tasks: Array<() => Promise<void>> = [];
for (const ref of refs) {
const path = this.resolveLoadPath_(ref);
const type = this.inferAssetType_(path);
if (!type) {
log.warn('asset', `preload: cannot determine asset type for ${ref}`);
failed.push({ ref, reason: 'unresolved' });
continue;
}
const load = this.typedLoadFor_(path, type);
if (!load) {
log.warn('asset', `preload: no loader for type '${type}' (${ref})`);
failed.push({ ref, type, reason: 'unresolved' });
continue;
}
tasks.push(() =>
load().then(() => {}).catch(e => {
log.warn('asset', `preload: failed to load ${ref}`, e);
failed.push({
ref, type, reason: 'load-failed',
error: e instanceof Error ? e.message : String(e),
});
}),
);
}
let loadedCount = 0;
const totalCount = tasks.length;
onProgress?.(0, totalCount);
const maxConcurrent = Math.max(1, options?.maxConcurrent ?? DEFAULT_PRELOAD_CONCURRENCY);
await runWithConcurrency(tasks, maxConcurrent, () => {
onProgress?.(++loadedCount, totalCount);
});
return { failed };
}
/** Asset type for a resolved path: catalog entry → manifest entry →
* extension match against the registered loaders → null. */
private inferAssetType_(path: string): string | null {
const catalogType = this.catalog.getEntry(path)?.type;
if (catalogType) return catalogType;
const manifestType = this.manifestModel_?.assetByPath(path)?.type;
if (manifestType) return manifestType;
const dot = path.lastIndexOf('.');
if (dot < 0) return null;
const ext = path.slice(dot).toLowerCase();
for (const loader of this.loaders_.values()) {
if (loader.extensions.includes(ext)) return loader.type;
}
return null;
}
/** Thunk that loads `path` through its type's canonical channel, or null
* when no loader handles the type. Textures/spine have dedicated entry
* points (refcount / two-file pairing); everything else is loadTyped. */
private typedLoadFor_(path: string, type: string): (() => Promise<unknown>) | null {
switch (type) {
case 'texture': return () => this.loadTexture(path);
case 'spine': return () => this.loadSpine(path);
case 'font':
case 'bitmap-font': return () => this.loadFont(path);
default:
return this.loaders_.has(type) ? () => this.loadTyped(type, path) : null;
}
}
// =========================================================================
// Raw Data (escape hatch)
// =========================================================================
async fetchJson<T = unknown>(ref: string): Promise<T> {
const path = this.resolveLoadPath_(ref);
const url = this.backend.resolveUrl(this.catalog.getBuildPath(path));
const text = await this.backend.fetchText(url);
return JSON.parse(text) as T;
}
async fetchBinary(ref: string): Promise<ArrayBuffer> {
const path = this.resolveLoadPath_(ref);
const url = this.backend.resolveUrl(this.catalog.getBuildPath(path));
return this.backend.fetchBinary(url);
}
async fetchText(ref: string): Promise<string> {
const path = this.resolveLoadPath_(ref);
const url = this.backend.resolveUrl(this.catalog.getBuildPath(path));
return this.backend.fetchText(url);
}
// =========================================================================
// Scene Asset Preloading
// =========================================================================
async preloadSceneAssets(
sceneData: SceneData,
onProgress?: (loaded: number, total: number) => void,
options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean },
): Promise<SceneAssetResult> {
return this.preloadSceneAssets_(sceneData, onProgress, options);
}
private async preloadSceneAssets_(
sceneData: SceneData,
onProgress?: (loaded: number, total: number) => void,
options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean },
recorder?: DependencyRecorder,
): Promise<SceneAssetResult> {
const missing: MissingAsset[] = [];
const discovered = discoverSceneAssets(sceneData, (ref) => this.resolveRef(ref));
for (const p of discovered.meshTextures) this.meshTextures_.add(p);
for (const p of discovered.meshMaterials) this.meshMaterials_.add(p);
for (const ref of discovered.unresolved) {
missing.push({ ref, reason: 'unresolved' });
}
if (discovered.unresolved.length > 0) {
log.warn(
'asset',
`${discovered.unresolved.length} unresolved asset ref(s)`,
discovered.unresolved,
);
}
const texturePaths = discovered.byType.get('texture') ?? new Set<string>();
const materialPaths = discovered.byType.get('material') ?? new Set<string>();
const fontPaths = discovered.byType.get('font') ?? new Set<string>();
// Anim clips load by their RAW serialized ref: components (SpriteAnimator.clip,
// Animator states) look clips up by that ref, and loadAnimClip aliases it to
// the resolved registration. Feeding the resolved path here (like the handle
// types) would strip the alias and leave play-realm lookups keyless.
const animClipPaths = discovered.rawByType.get('anim-clip') ?? new Set<string>();
const audioPaths = discovered.byType.get('audio') ?? new Set<string>();
const soundEventPaths = discovered.byType.get('sound-event') ?? new Set<string>();
const tilemapPaths = discovered.byType.get('tilemap') ?? new Set<string>();
const tilesetPaths = discovered.byType.get('tileset') ?? new Set<string>();
const timelinePaths = discovered.byType.get('timeline') ?? new Set<string>();
const fsmPaths = discovered.byType.get('statemachine') ?? new Set<string>();
const btPaths = discovered.byType.get('behaviortree') ?? new Set<string>();
const graphPaths = discovered.byType.get('scriptgraph') ?? new Set<string>();
const animatorPaths = discovered.byType.get('animatorcontroller') ?? new Set<string>();
const avatarPaths = discovered.byType.get('avatar') ?? new Set<string>();
const meshPaths = discovered.byType.get('mesh') ?? new Set<string>();
const environmentPaths = discovered.byType.get('environment') ?? new Set<string>();
const probeVolumePaths = discovered.byType.get('probeVolume') ?? new Set<string>();
const prefabPaths = discovered.byType.get('prefab') ?? new Set<string>();
const spinePairs = discovered.spines;
const textureHandles = new Map<string, number>();
const materialHandles = new Map<string, number>();
const fontHandles = new Map<string, number>();
const meshHandles = new Map<string, number>();
const environmentHandles = new Map<string, number>();
const probeVolumeHandles = new Map<string, number>();
const releaseCallbacks: ReleaseCallback[] = [];
const scope = new AssetScope();
const acquisitions: { type: string; path: string; lease: AssetLease }[] = [];
let loadedCount = 0;
const recordFailure = (path: string, label: string, err: unknown): void => {
recorder?.failed(path, err);
missing.push({
ref: path,
type: label,
reason: 'load-failed',
error: err instanceof Error ? err.message : String(err),
});
};
// Build task thunks instead of starting the promises eagerly — the
// worker pool below calls them one at a time per slot so a scene
// with hundreds of assets doesn't saturate the network or tie up
// image decoders all at once.
const tasks: Array<() => Promise<void>> = [];
/**
* One task per path. The receipt is recorded only when the acquire
* SUCCEEDED — a failed load owns nothing, so there is nothing for the
* scene to give back and nothing to guess about at unload.
*/
const timings: SceneAssetResult['timings'] = {};
const timedLoad = <R>(label: string, load: () => Promise<R>): Promise<R> => {
const began = preloadClock();
return load().finally(() => {
const ms = preloadClock() - began;
const t = timings[label] ??= { count: 0, ms: 0, slowestMs: 0 };
t.count++;
t.ms += ms;
t.slowestMs = Math.max(t.slowestMs, ms);
});
};
const pushAcquire = <T>(
paths: Set<string>,
acquire: (p: string) => Promise<AssetLease<T>>,
label: string,
handles?: Map<string, number>,
): void => {
for (const path of paths) {
tasks.push(() =>
timedLoad(label, () => acquire(path)).then(lease => {
// A baked asset's era owns these acquisitions. An ordinary
// scene owns them through the returned scope instead.
if (recorder) recorder.own(path, lease, label);
else scope.add(lease);
acquisitions.push({ type: label, path, lease });
releaseCallbacks.push(() => lease.release());
if (handles) {
handles.set(path, (lease.value as { handle?: number } | null)?.handle ?? 0);
}
}).catch(e => {
log.warn('asset', `Failed to load ${label}: ${path}`, e);
handles?.set(path, 0);
recordFailure(path, label, e);
}),
);
}
};
// Textures load through their AUTHORED ref, not the resolved path the
// handle map is keyed by: per-asset import settings (filter/wrap/sRGB and
// the 9-slice border) are looked up by the spelling a component carries,
// which is the resolver's documented contract. Resolution happens inside
// loadTexture anyway, so the bytes fetched are identical either way —
// feeding it the resolved path only strips the lookup of its key.
pushAcquire(
texturePaths,
p => this.acquireTexture(discovered.rawFor.get(p) ?? p),
'texture',
textureHandles,
);
pushAcquire(materialPaths, p => this.acquireTypedLease_<MaterialResult>('material', p),
'material', materialHandles);
pushAcquire(fontPaths, p => this.acquireTypedLease_<FontResult>('font', p), 'font', fontHandles);
pushAcquire(meshPaths, p => this.acquireTypedLease_<{ handle: number }>('mesh', p),
'mesh', meshHandles);
pushAcquire(environmentPaths, p => this.acquireTypedLease_<{ handle: number }>('environment', p),
'environment', environmentHandles);
pushAcquire(probeVolumePaths, p => this.acquireTypedLease_<{ handle: number }>('probeVolume', p),
'probeVolume', probeVolumeHandles);
// A pair, so not `pushAcquire` (which keys by one path); the receipt is
// the scene's exactly as every other one is. The runtime scene loader
// opts out: its second phase binds to entities that do not exist yet.
if (!options?.skipSpine) {
for (const pair of spinePairs) {
tasks.push(() =>
this.acquireSpineLease_(pair.skeleton, pair.atlas).then((lease) => {
if (recorder) recorder.own(spinePairKey(pair.skeleton, pair.atlas), lease, 'spine');
else scope.add(lease);
acquisitions.push({ type: 'spine', path: spinePairKey(pair.skeleton, pair.atlas), lease });
releaseCallbacks.push(() => lease.release());
}).catch(e => {
log.warn('asset', `Failed to load spine: ${pair.skeleton}`, e);
recordFailure(pair.skeleton, 'spine', e);
}),
);
}
}
pushAcquire(animClipPaths, p => this.acquireTypedLease_('anim-clip', p), 'anim-clip');
pushAcquire(tilemapPaths, p => this.acquireTypedLease_('tilemap', p), 'tilemap');
pushAcquire(tilesetPaths, p => this.acquireTypedLease_('tileset', p), 'tileset');
pushAcquire(timelinePaths, p => this.acquireTypedLease_('timeline', p), 'timeline');
pushAcquire(audioPaths, p => this.acquireTypedLease_('audio', p), 'audio');
pushAcquire(soundEventPaths, p => this.acquireTypedLease_('sound-event', p), 'sound-event');
// FSM/BT loaders register the parsed definition into the shared AI store
// under the asset path, so a StateMachineAgent/BehaviorTreeAgent whose
// fsm/bt is that path resolves once the scene finishes preloading.
pushAcquire(fsmPaths, p => this.acquireTypedLease_('statemachine', p), 'statemachine');
pushAcquire(btPaths, p => this.acquireTypedLease_('behaviortree', p), 'behaviortree');
pushAcquire(graphPaths, p => this.acquireTypedLease_('scriptgraph', p), 'scriptgraph');
pushAcquire(animatorPaths, p => this.acquireTypedLease_('animatorcontroller', p), 'animatorcontroller');
pushAcquire(avatarPaths, p => this.acquireTypedLease_('avatar', p), 'avatar');
pushAcquire(prefabPaths, p => this.acquireTypedLease_('prefab', p), 'prefab');
const totalCount = tasks.length;
onProgress?.(0, totalCount);
const maxConcurrent = Math.max(1, options?.maxConcurrent ?? DEFAULT_PRELOAD_CONCURRENCY);
const began = preloadClock();
await runWithConcurrency(tasks, maxConcurrent, () => {
onProgress?.(++loadedCount, totalCount);
});
const wallMs = preloadClock() - began;
if (totalCount > 0) {
const parts = Object.entries(timings).sort((a, b) => b[1].ms - a[1].ms)
.map(([k, t]) => `${k} ${t.count} (${Math.round(t.ms)}ms, slowest ${Math.round(t.slowestMs)}ms)`);
log.info('asset', `preloaded ${totalCount} asset(s) in ${Math.round(wallMs)}ms, ${maxConcurrent} at a time: ${parts.join(', ')}`);
}
// `unresolved` refs warn above; a load that THREW only reached `missing`,
// which callers may ignore — so a scene drew with no textures and no
// complaint, indistinguishable from a scene that has none.
warnFailedLoads(missing.filter((m) => m.reason === 'load-failed'));
return { textureHandles, materialHandles, fontHandles, meshHandles, environmentHandles,
probeVolumeHandles, releaseCallbacks, scope, acquisitions, missing, timings, wallMs };
}
resolveSceneAssetPaths(sceneData: SceneData, result: SceneAssetResult): void {
const { textureHandles, materialHandles, fontHandles, meshHandles,
environmentHandles, probeVolumeHandles } = result;
for (const entity of sceneData.entities) {
// Prefab-instance entries carry no inline components (a prefab ref +
// overrides); their handles bind when the prefab expands, not here.
if (!Array.isArray(entity.components)) continue;
for (const comp of entity.components) {
// Single source: the component def's declared asset fields.
// Handle write-back always keys off assetFields (the direct
// texture/material/font members), even for components whose
// discovery is driven by a discoverAssets callback instead.
const fields = getComponentAssetFieldDescriptors(comp.type);
for (const { field, type } of fields) {
const ref = comp.data[field];
if (typeof ref !== 'string' || !ref) continue;
// UUID refs resolve to their current path; plain paths
// pass through. Unknown UUID → null, handle will be 0
// (caller's getter returns 0 when the key is missing).
const path = this.resolveRef(ref);
if (path == null) {
comp.data[field] = getComponentDefaults(comp.type)?.[field] ?? 0;
continue;
}
switch (type) {
case 'texture': {
const handle = textureHandles.get(path) ?? 0;
comp.data[field] = handle;
this.recordHandlePath_('texture', handle, path);
// Ref spelling first (per-frame keys); the resolved
// path for packed frames is the shared page.
const atlasInfo = this.catalog.getAtlasFrame(ref) ?? this.catalog.getAtlasFrame(path);
if (atlasInfo) {
// COMPOSE with any authored sub-region rather than
// stomping it: the authored uv nests inside the frame.
const aOff = comp.data['uvOffset'] as { x: number; y: number } | undefined;
const aSc = comp.data['uvScale'] as { x: number; y: number } | undefined;
const ox = aOff?.x ?? 0, oy = aOff?.y ?? 0;
const sx = aSc?.x ?? 1, sy = aSc?.y ?? 1;
comp.data['uvOffset'] = {
x: atlasInfo.uvOffset[0] + ox * atlasInfo.uvScale[0],
y: atlasInfo.uvOffset[1] + oy * atlasInfo.uvScale[1],
};
comp.data['uvScale'] = {
x: sx * atlasInfo.uvScale[0],
y: sy * atlasInfo.uvScale[1],
};
if (atlasInfo.trim) {
comp.data['_trimOffsetX'] = atlasInfo.trim.offsetX;
comp.data['_trimOffsetY'] = atlasInfo.trim.offsetY;
comp.data['_trimSourceW'] = atlasInfo.trim.sourceW;
comp.data['_trimSourceH'] = atlasInfo.trim.sourceH;
}
}
break;
}
case 'material': {
const handle = materialHandles.get(path) ?? 0;
comp.data[field] = handle;
this.recordHandlePath_('material', handle, path);
break;
}
case 'font': {
const handle = fontHandles.get(path) ?? 0;
comp.data[field] = handle;
this.recordHandlePath_('font', handle, path);
break;
}
case 'mesh': {
comp.data[field] = meshHandles.get(path) ?? 0;
break;
}
case 'environment': {
comp.data[field] = environmentHandles.get(path) ?? 0;
break;
}
case 'probeVolume': {
comp.data[field] = probeVolumeHandles.get(path) ?? 0;
break;
}
}
}
}
}
}
/** Record scene users only after source IDs have been mapped to live World entities.
* Resolution is preparation; source IDs cannot be removed by World.onDespawn. */
trackSceneAssetReferences(scene: SceneData, entities: ReadonlyMap<number, number>): void {
const counter = this.refCounter_;
if (!counter) return;
for (const source of scene.entities) {
const entity = entities.get(source.id);
if (entity === undefined || !Array.isArray(source.components)) continue;
for (const comp of source.components) {
for (const { field, type } of getComponentAssetFieldDescriptors(comp.type)) {
const handle = comp.data[field];
if (typeof handle !== 'number' || !handle) continue;
const path = this.pathForHandle(type, handle);
if (path === null) continue;
if (type === 'texture') counter.addTextureRef(path, entity);
else if (type === 'material') counter.addMaterialRef(path, entity);
else if (type === 'font') counter.addFontRef(path, entity);
}
}
}
}
// =========================================================================
// Acquire — the same loads, but handing back an ownership receipt
// =========================================================================
/**
* Load a texture and get the receipt for THIS acquisition.
*
* The difference from {@link loadTexture} is who can be released correctly
* afterwards: a path names an asset, a lease names the instance this caller
* was handed. After `invalidate()` those are no longer the same thing.
*/
async acquireTexture(ref: string): Promise<AssetLease<TextureResult>> {
const { result, lease } = await this.acquireTextureVariant_(ref, true);
return this.textureLease_(lease, result);
}
/** {@link acquireTexture} for everything that goes through a typed loader. */
async acquireTyped<T>(type: string, ref: string): Promise<AssetLease<T>> {
try { return await this.acquireTypedLease_<T>(type, ref); }
catch (error) { throw preparationFailureReason(error); }
}
private async acquireTypedLease_<T>(type: string, ref: string): Promise<AssetLease<T>> {
const epoch = this.resetEpoch_;
this.assertLoading_(epoch);
const slot = await this.acquireSlot_<T>(type, ref);
try { this.assertLoading_(epoch); }
catch (error) { slot?.release(); throw error; }
if (slot) return slot;
const { value, lease } = await this.acquireTyped_<T>(type, ref);
return this.typedLease_(type, lease, value);
}
/**
* A claim on the slot for a registry-backed asset, or null when this type is
* not one. The ref the caller spelled is an ALIAS of the slot: a component
* carries that spelling and looks the asset up by it, while the load path is
* whatever this realm resolved it to.
*/
private async acquireSlot_<T>(type: string, ref: string): Promise<AssetLease<T> | null> {
const kind = this.registryKind_<T>(type);
if (!kind) return null;
// Keyed by identity, never by the locator: a content-addressed url is
// revision-specific, so a slot keyed by one is a slot PER REVISION and
// an update publishes into a new one while every holder reads the old.
const identity = this.assetIdentity_(ref);
// Answering to the ref as the caller spelled it too: a component looks
// the asset up by the spelling a scene serialized.
const names = ref === identity ? [identity] : [identity, ref];
return this.registrySlots_.acquire(kind, type, identity, names);
}
/**
* The owner-facing receipt for one ledger acquisition.
*
* `retain` goes through the ledger rather than through this class's load
* path: an owner splitting what it holds joins the era it already has, which
* after an invalidate is not the era a path resolves to.
*/
private textureLease_(
lease: AssetRefLease<number>, value: TextureResult,
): AssetLease<TextureResult> {
return {
key: lease.key, generation: lease.generation, value,
release: () => this.releaseTextureLease(lease),
retain: () => {
const child = this.textureRefs_.retain(lease);
return child ? this.textureLease_(child, value) : null;
},
};
}
/**
* A receipt for a texture this engine COMPOSED — no path, no generation, no
* cache entry to join. Its only identity is the handle, so the last holder
* destroys it rather than handing it back to a pool that could revive it.
*/
private ownedTextureLease_(value: TextureResult): AssetLease<TextureResult> {
return ownedAssetLease(`composed:${value.handle}`, value.handle, value, texture => {
requireResourceManager().releaseTexture(texture.handle);
evictTextureDimensions(texture.handle);
});
}
/** {@link textureLease_} for everything that goes through a typed loader. */
private typedLease_<T>(
type: string, lease: AssetRefLease<PreparedLoad<unknown>>, value: T,
): AssetLease<T> {
return {
key: lease.key, generation: lease.generation, value,
failedDependencies: lease.value.failedDependencies,
release: () => this.releaseTypedLease(type, lease),
retain: () => {
const child = this.genericRefs_.retain(lease);
return child ? this.typedLease_(type, child, value) : null;
},
};
}
// =========================================================================
// Release
// =========================================================================
releaseTexture(ref: string): void {
const path = this.resolveLoadPath_(ref);
for (const flip of [true, false]) {
const key = this.textureCacheKey_(path, flip);
const dropped = this.textureRefs_.releaseOldest(key);
if (!dropped) continue;
if (dropped.ambiguous) warnAmbiguousRelease_(key);
if (dropped.exhausted) this.disposeTexture_(key, dropped.value);
}
}
/**
* @internal Give back one texture acquisition by its receipt — exact even
* when `invalidate()` left two generations of the same path live. Callers
* hold an {@link AssetLease} and use its `release()`.
*/
releaseTextureLease(lease: AssetRefLease<number>): void {
const dropped = this.textureRefs_.release(lease);
if (dropped?.exhausted) this.disposeTexture_(lease.key, dropped.value);
}
/** The last SDK reference to a texture handle is gone: let the C++ pool decide. */
private disposeTexture_(key: string, handle: number): void {
// The pool decides what that means — free immediately (no budget), or
// retain as an evictable cache entry that the next load revives by key.
evictTextureDimensions(handle);
this.handleToPath_.delete(`texture:${handle}`);
// Only when it is still the cached value: a superseded handle left the
// cache when its generation ended, and the entry there now belongs to a
// generation with holders of its own.
if (this.textureCache_.get(key)?.handle === handle) this.textureCache_.delete(key);
requireResourceManager().releaseTexture(handle);
}
releaseFont(ref: string): void {
this.releaseTyped('font', ref);
}
releaseAudio(ref: string): void {
this.releaseTyped('audio', ref);
}
releaseAnimClip(ref: string): void {
this.releaseTyped('anim-clip', ref);
}
releaseTimeline(ref: string): void {
this.releaseTyped('timeline', ref);
}
releaseTilemap(ref: string): void {
this.releaseTyped('tilemap', ref);
}
releasePrefab(ref: string): void {
this.releaseTyped('prefab', ref);
}
/**
* Release a material obtained via {@link loadMaterial}, addressed by its
* handle (materials are tracked by handle, not ref, in the scene manager).
* Routes through the shared refcount + cache path so a material shared by
* two scenes survives until its last owner releases it, and the cache never
* hands the next load a destroyed handle. Destroying the handle directly
* (bypassing this) would strand a dead handle in the material cache.
*/
releaseMaterial(handle: number): void {
const path = this.pathForHandle('material', handle);
if (path !== null) this.releaseTyped('material', path);
}
/**
* Give back one reference to every asset in `byType` — what a scene, a
* document or a group acquired, in one call.
*
* Materials (handle-keyed) and skeletons (SpineManager's) are skipped.
* @beta Pre-1.0: the type vocabulary follows the loader registry.
*/
releaseAssets(byType: ReadonlyMap<string, ReadonlySet<string>>): void {
for (const [type, paths] of byType) {
if (type === 'material' || type === 'spine') continue;
for (const path of paths) {
if (type === 'texture') this.releaseTexture(path);
else this.releaseTyped(type, path);
}
}
}
/**
* @internal Release one reference to a typed asset by path — the door the
* group channel table uses. Game code calls the named release* methods.
*/
releaseTyped(type: string, ref: string): void {
const path = type === 'spine'
? spinePairKey(this.resolveLoadPath_(ref), this.spineAtlasOf_(this.resolveLoadPath_(ref)))
: this.resolveLoadPath_(ref);
const kind = this.registryKind_(type);
if (kind) {
this.registrySlots_.releaseByName(type, this.assetIdentity_(ref));
return;
}
// NOT gated on a live cache entry: a generation superseded by
// invalidate() is out of the cache while its holders still owe a
// release, and returning here left their asset unreachable.
const key = `${type}:${path}`;
const dropped = this.genericRefs_.releaseOldest(key);
if (!dropped) return;
if (dropped.ambiguous) warnAmbiguousRelease_(key);
if (dropped.exhausted) this.disposeGeneric_(type, path, dropped.value);
}
/**
* @internal The typed twin of {@link releaseTextureLease}; callers use the
* lease's own `release()`.
*/
releaseTypedLease(type: string, lease: AssetRefLease<PreparedLoad<unknown>>): void {
const dropped = this.genericRefs_.release(lease);
if (!dropped?.exhausted) return;
const path = lease.key.slice(type.length + 1);
this.disposeGeneric_(type, path, dropped.value);
}
/** The last reference to a typed asset is gone: hand it to its loader. */
private disposeGeneric_(type: string, path: string, era: PreparedLoad<unknown>): void {
const cache = this.genericCache_.get(type);
if (cache && cache.get(path) === era) cache.delete(path);
this.retire_(type, era);
}
/** End one handle-bound era: its loader destroys what it made, then what its
* preparation acquired goes back — in that order, since the value is what
* is still using it. */
private retire_(type: string, era: PreparedLoad<unknown>): void {
if (this.retired_.has(era)) return;
this.retired_.add(era);
const handle = (era.value as { handle?: unknown } | null)?.handle;
if (typeof handle === 'number') this.handleToPath_.delete(`${type}:${handle}`);
disposeAll([
() => this.loaders_.get(type)?.unload?.(era.value),
() => era.dependencies.releaseAll(),
], dispose => dispose());
}
/**
* Drop every internal cache entry for `ref` so the next `loadTexture` /
* `loadMaterial` / ... fetches fresh bytes. Call this when the source
* file changed on disk (hot reload).
*
* Any GPU handle that was already handed out stays valid and keeps
* rendering — that's the caller's concern to release. The next load
* produces a brand-new handle from the updated bytes; the old handle
* is evicted from the cache but not freed, so currently-rendering
* entities don't flicker.
*
* If any cache held `ref`, invokes every listener registered via
* `onInvalidate` with the original ref. Listeners that throw are
* caught and logged — one bad subscriber can't prevent other
* subscribers from observing the invalidation.
*
* What was BUILT from `ref` ends too. The plan is read BEFORE anything is
* dropped, and walked deepest-first with each group awaiting the one before
* it: a parent re-prepared too early acquires the era it already had.
*
* Returns true if any cache held `ref` itself.
*/
invalidate(ref: string): boolean {
const plan = this.rebuildPlan_(ref);
// A failed preparation has no live era, but its canonical cooldown
// rejection still records why it failed. Clear it before rebuilding
// holders reached by the restored source, rather than reusing failure.
const source = this.assetIdentity_(ref);
for (const cache of this.genericCache_.values()) {
for (const [key, error] of cache.failures()) {
if (error instanceof PreparationFailure
&& error.sources.some(path => this.assetIdentity_(path) === source)) cache.invalidate(key);
}
}
const { hit, rebuilt } = this.invalidateSource_(ref);
if (plan.length > 0) this.track_(rebuilt.then(() => this.rebuildAssetGraph_(plan)));
return hit;
}
/**
* Resolves when every propagation started so far has landed.
*
* The ASSET graph only. What reads it — a component bound to a handle — is
* the second barrier, and it moves on a frame rather than here: see the
* live-binding coordinator's `settled`.
*
* @internal
*/
async assetGraphSettled(): Promise<void> {
// A rebuild can start another (a group awaits the one before it), so
// draining once is not the same as being settled.
while (this.settling_.size > 0) {
const inFlight = [...this.settling_];
await Promise.all(inFlight);
for (const work of inFlight) this.settling_.delete(work);
}
}
/** What a change to `ref` reaches. Not filtered by path: an asset that
* happens to live at the changed file can still be what the chain reaches
* LAST, and dropping it there is the same erasure one level up. */
private rebuildPlan_(ref: string): AssetIdentity[][] {
return rebuildPlan(this.resolveLoadPath_(ref), {
ofSource: (path) => this.dependentsOfSource(path),
ofAsset: (asset) => this.dependentsOfAsset(asset),
});
}
/** Count one propagation as in flight until it lands. It answers to nobody
* in the ordinary case, so a failure is reported here rather than thrown at
* whoever happens to be waiting. */
private track_(work: Promise<void>): void {
const settled = work.catch((e: unknown) => {
log.warn('asset', 'propagating a change failed; what it reached keeps what it has', e);
});
this.settling_.add(settled);
void settled.finally(() => this.settling_.delete(settled));
}
/** Each group only once everything it was built from has landed. */
private async rebuildAssetGraph_(plan: AssetIdentity[][]): Promise<void> {
for (const group of plan) {
await Promise.all(group.map((vertex) => this.invalidateAsset_(vertex).rebuilt));
}
}
/**
* End every era at one PATH: a file changed, and whatever it names changed
* with it. What `invalidate(ref)` is, and what a hot update's changed key is.
*/
private invalidateSource_(ref: string): { hit: boolean; rebuilt: Promise<void> } {
let hit = false;
const work: Array<Promise<void>> = [];
for (const type of this.loaders_.keys()) {
const ended = this.invalidateAsset_({ type, path: ref });
hit = ended.hit || hit;
work.push(ended.rebuilt);
}
return { hit, rebuilt: Promise.all(work).then(() => undefined) };
}
/**
* End ONE asset's era — its type all the way down. A path can name a texture
* and a material, and what one of them acquired changing is not a change to
* the other; a plan that knows the difference and then ends both has thrown
* away what it knew.
*/
private invalidateAsset_(asset: AssetIdentity): { hit: boolean; rebuilt: Promise<void> } {
const { type } = asset;
const path = this.resolveLoadPath_(asset.path);
// Held by a cache or by a loader's own residency: what a listener is
// told about. A slot swaps its era instead, and reports nothing.
let dropped = false;
let oldValue: unknown;
if (type === 'texture') {
// The handle bound to this path, captured BEFORE the caches drop it,
// so a rebind listener can swap it in live components.
oldValue = this.textureCache_.get(this.textureCacheKey_(path, true))?.handle ?? 0;
const rm = getResourceManager();
// Both flip variants: the cache key carries the flag. The C++ pool's
// residency identity is severed too — an evictable entry under this
// key is freed and can never be revived with stale bytes.
for (const flip of [true, false]) {
const key = this.textureCacheKey_(path, flip);
if (this.textureCache_.invalidate(key)) dropped = true;
// The ledger is NOT dropped: holders of the outgoing generation
// still owe a release, and forgetting them strands their texture
// with nobody able to free it. The era still ends here.
this.textureRefs_.supersede(key);
if (typeof rm?.invalidateTexturePath === 'function' && rm.invalidateTexturePath(key)) {
dropped = true;
}
}
// Skeletal atlas pages register the image path without a flip suffix.
// End their residency too, even when no SDK texture cache holds them.
if (typeof rm?.invalidateTexturePath === 'function' && rm.invalidateTexturePath(path)) {
dropped = true;
}
} else {
const cache = this.genericCache_.get(type);
if (cache) {
oldValue = cache.get(path)?.value;
if (cache.invalidate(path)) dropped = true;
}
// The ledger stays, for the same reason as a texture's.
this.genericRefs_.supersede(`${type}:${path}`);
}
// A registry-backed asset has no cache entry to drop and no handle to
// swap: the update IS a new era published under the same names.
const slot = this.republishSlot_(type, asset.path);
// Loader-owned residency (e.g. the AudioAPI warm cache) can outlive the
// Assets-level entry — sever it so a warm-cache revive can never serve
// stale bytes after a hot reload.
if (this.loaders_.get(type)?.invalidate?.(path)) dropped = true;
// The reverse handle→path records of this kind are stale now: a reload
// mints new handles, and the old ones must stop naming the asset.
for (const [key, held] of this.handleToPath_) {
if (held === path && key.startsWith(`${type}:`)) this.handleToPath_.delete(key);
}
if (dropped) {
this.fireInvalidate_({ ref: asset.path, type: type as AssetFieldType, oldValue });
}
return { hit: dropped || slot.found, rebuilt: slot.rebuilt };
}
/**
* Prepare a new era for the slot (type, ref) names, and publish it
* atomically. By IDENTITY: the slot is keyed by what the asset is, and this
* preparation resolves where the current revision serves it.
*/
private republishSlot_(type: string, ref: string): { found: boolean; rebuilt: Promise<void> } {
const kind = this.registryKind_(type);
const identity = this.assetIdentity_(ref);
if (!kind || !this.registrySlots_.has(type, identity)) {
return { found: false, rebuilt: Promise.resolve() };
}
const rebuilt = this.registrySlots_.republish(kind, type, identity).then(
() => undefined,
(e: unknown) => {
log.warn('asset', `hot update: re-publishing "${ref}" failed; holders keep the era they have`, e);
},
);
return { found: true, rebuilt };
}
/** {@link republishSlot_} for every type this ref names one of — a changed
* FILE, which does not say what kind of asset lives at it. */
private republishSlots_(ref: string): { found: boolean; rebuilt: Promise<void> } {
const work: Array<Promise<void>> = [];
let found = false;
for (const type of this.loaders_.keys()) {
const slot = this.republishSlot_(type, ref);
found = slot.found || found;
work.push(slot.rebuilt);
}
return { found, rebuilt: Promise.all(work).then(() => undefined) };
}
/** Fire every onInvalidate listener with one generation's ending. Isolates
* throws. Shared by {@link invalidate} and {@link applyUpdate}. */
private fireInvalidate_(event: AssetInvalidation): void {
for (const listener of this.invalidateListeners_) {
try {
listener(event);
} catch (e) {
log.warn('asset', 'onInvalidate listener threw', e);
}
}
}
/**
* Subscribe to cache invalidations. The listener fires once per
* successful `invalidate(ref)` call with the original ref (not the
* resolved path). Returns an unsubscribe function.
*
* Typical use: a scene-graph controller or renderer that holds cached
* handles for assets — subscribe to re-bind / re-load on hot reload
* so stale GPU handles stop being rendered.
*/
onInvalidate(listener: InvalidateListener): () => void {
this.invalidateListeners_.add(listener);
return () => {
this.invalidateListeners_.delete(listener);
};
}
/**
* @internal Live entry counts for the resource census.
*
* Cache sizes are not expected to return to baseline — that is what a cache
* is for. `refCounts` and `handlePaths` are: every load handing one out has a
* release taking it back. `pendingLoads` and `propagations` should be zero at rest.
*/
sizes(): {
textureCached: number;
pendingLoads: number;
/** Rebuilds of dependents still running after an invalidation. */
propagations: number;
refCounts: number;
refRows: number;
genericCaches: number;
genericCached: number;
handlePaths: number;
invalidateListeners: number;
registrySlots: number;
trackedRefRows: number;
} {
const tex = this.textureCache_.sizes();
let genericCached = 0;
let pending = tex.pending;
for (const cache of this.genericCache_.values()) {
const s = cache.sizes();
genericCached += s.cached;
pending += s.pending;
}
return {
textureCached: tex.cached,
pendingLoads: pending,
propagations: this.settling_.size,
refCounts: this.textureRefs_.size + this.genericRefs_.size,
refRows: this.textureRefs_.rows + this.genericRefs_.rows,
genericCaches: this.genericCache_.size,
genericCached,
handlePaths: this.handleToPath_.size,
invalidateListeners: this.invalidateListeners_.size,
registrySlots: this.registrySlots_.size,
trackedRefRows: this.refCounter_?.getTotalRefRows() ?? 0,
};
}
/**
* What is explicitly owned by the whole asset realm.
*
* Its life is this instance's. Entity bindings use scene or entity scopes,
* including runtime entities with no scene, so their resources can end sooner.
*
* @internal
*/
get appScope(): AssetScope {
return this.appScope_;
}
/**
* What entities own for themselves — runtime entities with no scene and
* persistent entities that outlived theirs. Ends at the entity's despawn.
*
* @internal
*/
get entityScopes(): EntityAssetScopes {
return this.entityScopes_;
}
/** @internal A standalone bake uses the same acquisition transaction as a graph recipe. */
async preparePrefab(ref: string, overrides: readonly PrefabOverride[] = []): Promise<PreparedPrefab> {
const epoch = this.resetEpoch_;
try {
const era = await this.prepared_(ctx => this.bakePrefab_(this.resolveLoadPath_(ref),
ctx as LoadContext & { recorder: DependencyRecorder }, overrides));
if (epoch !== this.resetEpoch_) {
era.dependencies.releaseAll();
throw new Error(`Assets were released while "${ref}" was preparing; it has no owner. Load it again.`);
}
return { ...era, ref, release: () => era.dependencies.releaseAll() };
} catch (error) { throw preparationFailureReason(error); }
}
releaseAll(): void {
if (this.releasing_) return;
this.releasing_ = true;
// Pending loads lose ownership even if a user-provided unload throws.
this.resetEpoch_++;
this.abandoned_.clear();
try {
disposeAll([
() => {
const pending = [...this.preparations_];
this.preparations_.clear();
disposeAll(pending, recorder => recorder.rollback());
},
// Normal receipts first, then every remaining generation.
() => this.appScope_.releaseAll(),
() => this.registrySlots_.releaseAll(),
() => {
const handles = new Set<number>();
for (const info of this.textureCache_.values()) handles.add(info.handle);
this.textureCache_.clearAll();
for (const { value } of this.textureRefs_.drain()) handles.add(value);
if (handles.size === 0) return;
const rm = requireResourceManager();
disposeAll([...handles], handle => {
evictTextureDimensions(handle);
rm.releaseTexture(handle);
});
},
() => {
for (const cache of this.genericCache_.values()) cache.clearAll();
this.genericCache_.clear();
const generations = this.genericRefs_.drain();
disposeAll(generations, ({ key, value }) => this.retire_(key.slice(0, key.indexOf(':')), value));
},
], dispose => dispose());
} finally {
const meshLoader = this.getLoader<MeshResult>('mesh');
if (meshLoader instanceof MeshAssetLoader) for (const handle of this.builtMeshes_.keys()) meshLoader.releaseData(handle);
this.builtMeshes_.clear();
this.handleToPath_.clear();
this.releasing_ = false;
}
}
// =========================================================================
// Spine Controller
// =========================================================================
getTextureLoader(): TextureLoader {
return this.textureLoader_;
}
/**
* What the textures this realm loaded became on the GPU, and which compressed
* formats the device samples at all. @experimental
*
* The upload half; what the BUILD shipped is the cook's own record. A realm
* that plays source images still answers `deviceFormats` — the capability a
* cooked payload would meet here.
*/
textureFormatReport(): TextureFormatReport {
return this.textureLoader_.formatReport();
}
setAssetRefResolver(resolver: AssetRefResolver): void {
this.assetRefResolver_ = resolver;
}
private readonly assetProblems_ = new Map<string, readonly string[]>();
private assetProblemListener_: ((asset: string, problems: readonly string[]) => void) | null = null;
/**
* What is wrong with an asset that loaded: the parts of it that were left out, each said once. Empty when it is whole (or was never
* loaded). A material whose texture would not load, or whose value has a shape nothing reads, is here and not in a failed load.
* @experimental
*/
getAssetProblems(asset: string): readonly string[] {
return this.assetProblems_.get(asset) ?? [];
}
/** Hear every change to an asset's problems (the editor's diagnostics). One listener; null removes it. @experimental */
setAssetProblemListener(listener: ((asset: string, problems: readonly string[]) => void) | null): void {
this.assetProblemListener_ = listener;
}
getAssetRefResolver(): AssetRefResolver | null {
return this.assetRefResolver_;
}
/**
* Attach optional usage monitoring. Scene publication records runtime
* entity IDs through trackSceneAssetReferences; the shared World binding
* removes them on despawn and follows the active asset resource. Plugin
* and runtime factories install it; manually created Assets default to
* no tracking until a counter is attached.
*/
setRefCounter(counter: AssetRefCounter): void {
this.refCounter_ = counter;
}
getRefCounter(): AssetRefCounter | null {
return this.refCounter_;
}
/**
* Resolve any serialized asset ref (UUID or plain path) to a concrete
* path. Returns null when a UUID ref can't be matched to a known
* asset. Without a registry/resolver configured, refs pass through
* unchanged — legacy path-only scenes keep working.
*/
resolveRef(ref: string): string | null {
if (isBuiltinAssetRef(ref)) return ref;
if (this.assetRefResolver_) return this.assetRefResolver_(ref);
return ref;
}
/**
* The load path a ref resolves to — resolver plus addressable Catalog,
* the same two steps every typed load performs. This is the key a loader
* registers a data asset under, so runtime stores keyed by registration
* path (FSM/BT/timeline/tilemap via `resolveAssetKey`) must look up with
* THIS: `resolveRef` alone diverges once the Catalog carries mappings.
*/
resolveLoadPath(ref: string): string {
return this.resolveLoadPath_(ref);
}
/**
* Canonical path-resolution for all typed load methods.
* Runs the AssetRefResolver first so `@uuid:...` refs map to their real
* project path, then applies the addressable Catalog for any further
* indirection. If the resolver returns null (unknown UUID), we fall back
* to the Catalog on the original ref — the loader will 404 with a clear
* error rather than silently succeeding on a nonsense URL.
*
* Historically each load method called `this.catalog.resolve(ref)`
* directly, which completely bypassed the AssetRefResolver. Editors that
* serialized asset refs as `@uuid:...` could never resolve them at load
* time — textures silently rendered white. This helper closes that gap.
*/
private resolveLoadPath_(ref: string): string {
// Built-in geometry names code, not a file. Every realm's resolver turns a
// non-URL ref into one (the play realm prefixes an origin), so a ref that
// has nothing to resolve has to say so before resolution, not after.
if (isBuiltinAssetRef(ref)) return ref;
// A `remote`-group asset (per the active addressable manifest) resolves to
// its CDN url — so a scene @uuid ref to a remote asset loads from, and
// hot-updates with, the CDN, not just loadGroup'd DLC assets. Gated on a
// remote root being set, so same-origin realms (editor Play, a build with
// no CDN) keep their normal resolver + base-prefixing untouched. It is
// the one step that carries a REVISION, which is why identity stops
// short of it.
const remote = this.remoteAssetPath_(ref);
if (remote != null) return remote;
// Deliberately NOT assetIdentity_: for a remote-group asset that answers
// with the ADDRESS, and the package carries the STAGED name. Where the
// bytes are is the realm's question, so its resolver gets it.
const resolved = this.assetRefResolver_?.(ref) ?? ref;
return this.catalog.resolve(resolved);
}
/** CDN url of `ref` when it names a `remote`-group asset AND a remote root is
* set; null otherwise (caller falls back to the normal resolver). */
private remoteAssetPath_(ref: string): string | null {
if (!this.remoteRoot_) return null;
const model = this.manifestModel_;
if (!model) return null;
const key = ref.startsWith(UUID_REF_PREFIX)
? ref.slice(UUID_REF_PREFIX.length).toLowerCase()
: ref;
const path = model.remoteAssetPath(key) ?? model.remoteAssetPath(ref);
return path != null ? this.remoteUrlFor_(path) : null;
}
/**
* What a ref MEANS in this realm, with no revision in it.
*
* Distinct from {@link resolveLoadPath_}, which goes on to where that asset
* is served from NOW. Identity is what a slot is keyed by and what two
* spellings agree on; a locator is what one preparation reads.
*/
private assetIdentity_(ref: string): string {
if (isBuiltinMeshRef(ref)) return ref;
// A manifest names one asset three ways — record key, address, build
// path — and only it knows they are the same asset. Folding them here is
// what keeps a uuid ref and a path ref on ONE slot.
const named = this.manifestModel_?.remoteAssetIdentity(ref);
if (named != null) return named;
const resolved = this.assetRefResolver_?.(ref) ?? ref;
return this.catalog.resolve(resolved);
}
// =========================================================================
// Private
// =========================================================================
private registerBuiltinLoaders(): void {
this.register(this.textureLoader_);
this.register(this.spineLoader_);
this.register(new MaterialShaderAssetLoader());
this.register(new MaterialAssetLoader());
this.register(new FontAssetLoader());
// The engine core however it is embedded: the module on the web, the host's
// bindings on a device. Taking only the module made these two web-only by
// construction — a packaged game passes `module: null`.
const core = (): EngineApi | null => this.module_ ?? nativeEngineApi();
this.register(new MeshAssetLoader(core));
this.register(new EnvironmentAssetLoader(core));
this.register(new ProbeVolumeAssetLoader(core));
this.register(new MeshSdfAssetLoader());
this.register(new MeshCardsAssetLoader());
// The audio loader needs the AudioAPI outside load() too (unload /
// invalidate have no LoadContext), so it shares Assets' lazy accessor.
this.register(new AudioAssetLoader(() => this.getAudio_()));
this.register(new AnimClipAssetLoader());
this.register(new PrefabAssetLoader());
// A recipe is bound to an exact era, just like a resolved material.
// Use the same pending cache, generation ledger and dependency graph.
this.register<PreparedPrefab>({
type: 'prepared-prefab', extensions: [],
load: (path, context) => this.bakePrefab_(path, context as LoadContext & { recorder: DependencyRecorder }),
unload: (prepared) => prepared.release(),
});
this.register(new LocaleAssetLoader());
this.register(new JsonAssetLoader());
this.register(new SoundEventAssetLoader());
// …and whatever an optional subsystem brought with it. A loader names
// its subsystem's parser, so one the core constructs is one every
// package carries.
for (const loader of optionalAssetLoaders()) this.register(loader);
}
private textureCacheKey_(path: string, flip: boolean): string {
return textureResidencyKey(path, flip);
}
private async loadTyped<T>(type: string, ref: string): Promise<T> {
try { return (await this.acquireTyped_<T>(type, ref)).value; }
catch (error) { throw preparationFailureReason(error); }
}
private async acquireTyped_<T>(
type: string, ref: string,
): Promise<{ value: T; lease: AssetRefLease<PreparedLoad<unknown>> }> {
const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;
if (!loader) {
throw new Error(`No loader registered for type: ${type}`);
}
if (!loader.load) {
throw new Error(`Loader for "${type}" publishes by name; acquire it through its slot`);
}
const load = loader.load.bind(loader);
const path = this.resolveLoadPath_(ref);
return this.acquirePrepared_<T>(type, path, ref, (ctx) => load(path, ctx));
}
/**
* One era of one handle-bound asset, under the KEY that identifies it — the
* path for everything whose identity is a path, and the PAIR for spine,
* whose skeleton with another atlas is another asset. One ownership
* algorithm, differing only in what it calls one asset.
*/
private async acquirePrepared_<T>(
type: string, key: string, ref: string, prepare: (ctx: LoadContext) => Promise<T>,
): Promise<{ value: T; lease: AssetRefLease<PreparedLoad<unknown>> }> {
this.assertLoading_();
const epoch = this.resetEpoch_;
const era = await this.genericCacheFor_(type).getOrLoad(key, () =>
this.prepared_(async (ctx) => ({ value: await prepare(ctx) as unknown })),
);
// BEFORE acquiring, as with textures: a realm that let go while this
// loaded has drained the ledger this row would go in, so nothing would
// ever unload it.
if (epoch !== this.resetEpoch_) {
this.retire_(type, era);
throw new Error(
`Assets were released while "${ref}" was loading; it has no owner. Load it again.`,
);
}
const lease = this.genericRefs_.acquire(`${type}:${key}`, era);
const result = era.value as T;
const handle = (result as { handle?: unknown } | null)?.handle;
if (typeof handle === 'number' && handle !== 0) this.recordHandlePath_(type, handle, key);
return { value: result, lease };
}
/** The cache of current eras for one handle-bound type. A load that lands
* after its own deadline was never handed to anyone, so this is the last
* place that knows it and what it acquired. */
private genericCacheFor_(type: string): AsyncCache<PreparedLoad<unknown>> {
let cache = this.genericCache_.get(type);
if (!cache) {
cache = new AsyncCache<PreparedLoad<unknown>>((era) => this.retire_(type, era));
this.genericCache_.set(type, cache);
}
return cache;
}
/**
* What THIS realm publishes for a ref-bound asset — the answer a runtime
* lookup reads, and the only copy of it.
*
* By the ref as spelled or the path it resolves to: a slot answers to both,
* so a lookup site need not know which spelling a scene serialized.
*
* @internal
*/
resolveRegistryAsset<T>(type: string, ref: string): T | undefined {
return (this.registrySlots_.published(type, ref)
?? this.registrySlots_.published(type, this.assetIdentity_(ref))) as T | undefined;
}
/** @internal Changes when a registry type publishes, replaces or withdraws an era. */
registryAssetVersion(type: string): number {
return this.registrySlots_.version(type);
}
/**
* What the current era of a ref-bound asset took — the dependency graph as a
* PROJECTION of acquisitions, never a table anyone maintains.
*
* @internal
*/
dependenciesOf(type: string, ref: string): readonly DependencyReceipt[] {
const own = this.registrySlots_.dependenciesOf(type, ref);
if (own.length > 0) return own;
const byIdentity = this.registrySlots_.dependenciesOf(type, this.assetIdentity_(ref));
if (byIdentity.length > 0) return byIdentity;
return this.genericCache_.get(type)?.get(this.resolveLoadPath_(ref))?.edges ?? [];
}
/**
* The asset types a component holds BY HANDLE — the loaders with a `load`
* door. What a live rebind can migrate: a ref-bound asset's slot swaps
* under the name a field already holds, so there is nothing to move.
*
* @internal
*/
handleBoundTypes(): string[] {
const types: string[] = [];
for (const [type, loader] of this.loaders_) {
if (loader.load) types.push(type);
}
return types;
}
/**
* Every asset of this realm whose CURRENT era took `ref` — the reverse of
* {@link dependenciesOf}, walked from the eras so there is no table to keep.
* By canonical identity: a receipt says what the acquisition ASKED for (a
* `@uuid:` ref, a document-relative path) and a change names a file.
*
* @internal
*/
dependentsOfSource(ref: string): AssetIdentity[] {
// Both meanings of a file: whoever READ it, and whoever acquired the
// asset that lives at it.
return this.dependents_(ref, isInvalidatable);
}
/**
* Every asset of this realm that ACQUIRED this one — the edge to follow once
* the walk is past the file that changed. A source read is NOT one: those
* bytes are exactly as their reader read them, and what ended here is this
* asset's own generation.
*
* @internal
*/
dependentsOfAsset(asset: AssetIdentity): AssetIdentity[] {
return this.dependents_(asset.path, (e) => e.kind === 'owned' && e.type === asset.type);
}
/** Every era with an edge that `names` — the walk both doors share. */
private dependents_(ref: string, names: (e: DependencyReceipt) => boolean): AssetIdentity[] {
const canonical = new Map<string, string>();
const identify = (path: string): string => {
let known = canonical.get(path);
if (known === undefined) {
known = this.resolveLoadPath_(path);
canonical.set(path, known);
}
return known;
};
const target = identify(ref);
const out: AssetIdentity[] = [];
for (const era of this.eras_()) {
if (era.edges.some((e) => names(e) && identify(e.path) === target)) {
out.push({ type: era.type, path: era.path });
}
}
return out;
}
/** Every live era of this realm, published under a name or held by handle. */
private *eras_(): Generator<{ type: string; path: string; edges: readonly DependencyReceipt[] }> {
for (const era of this.registrySlots_.eras()) {
yield { type: era.type, path: era.key, edges: era.edges };
}
const seen = new Set<PreparedLoad<unknown>>();
for (const [type, cache] of this.genericCache_) {
for (const [path, era] of cache.entries()) {
seen.add(era);
yield { type, path, edges: era.edges };
}
}
// Invalidating removes residency, not ownership. A failed refresh can
// keep an outgoing recipe in a graph; its nested dependencies must still
// lead back to that graph when their sources recover.
for (const [key, generations] of this.genericRefs_.entries()) {
const split = key.indexOf(':');
const type = key.slice(0, split), path = key.slice(split + 1);
for (const { value: era } of generations) {
if (seen.has(era)) continue;
seen.add(era);
yield { type, path, edges: era.edges };
}
}
}
/**
* Everything this realm publishes of one type. What a schedule analysis
* reads to learn what the graphs THIS app loaded reach for.
*
* @internal
*/
publishedRegistryAssets<T>(type: string): T[] {
return this.registrySlots_.publishedOf(type) as T[];
}
/**
* The slot table's view of one registry-backed loader — the LoadContext
* bound in, so the table stays about ownership and knows nothing about how
* any particular kind of asset is parsed.
*/
private registryKind_<T>(type: string): RegistryAssetKind<T> | null {
const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;
const registry = loader?.registry;
if (!registry) return null;
// The locator is resolved HERE, once per era: the slot holds an identity,
// and where that asset is served from is a property of the revision the
// preparation runs in.
return {
prepare: (identity) => this.prepared_(
(ctx) => registry.prepare(this.resolveLoadPath_(identity), ctx),
),
};
}
/** A generation-bound recipe through the ordinary typed-asset door. */
private preparePrefabLease_(ref: string): Promise<AssetLease<PreparedPrefab>> {
return this.acquireTypedLease_<PreparedPrefab>('prepared-prefab', ref);
}
private bakePrefab_(path: string, ctx: LoadContext & { recorder: DependencyRecorder },
overrides: readonly PrefabOverride[] = []): Promise<PreparedPrefab> {
return preparePrefabFromSource({
loadPrefab: async (ref) => (await ctx.acquireAsset<PrefabResult>('prefab', ref)).value,
preloadSceneAssets: scene => this.preloadSceneAssets_(scene, undefined, undefined, ctx.recorder),
resolveSceneAssetPaths: (scene, result) => this.resolveSceneAssetPaths(scene, result),
trackSceneAssetReferences: (scene, entities) => this.trackSceneAssetReferences(scene, entities),
resolveRef: ref => this.resolveRef(ref),
entityScopes: this.entityScopes,
}, path, overrides);
}
/**
* Run one preparation: what the loader takes IS the result's ownership and
* IS the graph's edges. A transaction, because an acquisition on the way to
* a value that never arrives has no owner — the thing that would have held
* it does not exist.
*/
private async prepared_<T extends object>(
work: (ctx: LoadContext) => Promise<T>,
): Promise<T & Preparation> {
this.assertLoading_();
const recorder = new DependencyRecorder();
this.preparations_.add(recorder);
try {
return recorder.commit(await work(this.recordingContext_(recorder)));
} catch (e) {
throw recorder.abort(e);
} finally { this.preparations_.delete(recorder); }
}
/** The load context one preparation sees: every door that takes something
* reports it, and the plain readers stay plain. */
private recordingContext_(recorder: DependencyRecorder): LoadContext & { recorder: DependencyRecorder } {
const base = this.getLoadContext_();
const epoch = this.resetEpoch_;
const attempt = async <T>(ref: string, work: () => Promise<T>): Promise<T> => {
try { this.assertLoading_(epoch); return await work(); }
catch (error) { recorder.failed(ref, error); throw preparationFailureReason(error); }
};
const read = async <T>(ref: string, work: () => Promise<T>): Promise<T> => {
const result = await attempt(ref, work);
this.assertLoading_(epoch);
return result;
};
const take = async <T>(ref: string, work: () => Promise<AssetLease<T>>, type?: string): Promise<AssetLease<T>> => {
// Own first: if teardown crossed this await, rollback must still
// return the receipt before the obsolete loader sees its value.
const lease = recorder.own(ref, await attempt(ref, work), type);
this.assertLoading_(epoch);
return lease;
};
return {
...base,
recorder,
loadText: path => read(path, () => base.loadText(path)),
loadBinary: path => read(path, () => base.loadBinary(path)),
loadTexture: (path, flipY) => read(path, () => base.loadTexture(path, flipY)),
decodePixels: path => read(path, () => base.decodePixels!(path)),
acquireTexture: async (path, flipY) =>
take(path, () => base.acquireTexture(path, flipY), 'texture'),
acquireAsset: async (type, ref) => take(ref, () => this.acquireTypedLease_(type, ref), type),
resolveRef: ref => this.resolveRef(ref),
preparePrefab: async (ref) => take(ref, () => this.preparePrefabLease_(ref), 'prepared-prefab'),
createOwnedTexture: async (width, height, pixels, flipY) => {
this.assertLoading_(epoch);
const lease = await base.createOwnedTexture!(width, height, pixels, flipY);
recorder.own(`composed:${lease.value.handle}`, lease);
this.assertLoading_(epoch);
return lease;
},
readSource: async (ref) => {
// The edge records what was ASKED for; where the build put
// those bytes is this door's business, as it is for a texture.
// A loader resolving first records an identity nothing names.
recorder.read(ref);
return read(ref, () => base.loadText(this.catalog.getBuildPath(ref)));
},
};
}
private getLoadContext_(): LoadContext {
if (this.loadContext_) return this.loadContext_;
const self = this;
this.loadContext_ = {
backend: this.backend,
catalog: this.catalog,
resourceManager: requireResourceManager() as CppResourceManager,
async loadTexture(path: string, flipY?: boolean): Promise<TextureResult> {
if (flipY === false) {
return self.loadTextureRaw(path);
}
return self.loadTexture(path);
},
async acquireTexture(path: string, flipY?: boolean): Promise<AssetLease<TextureResult>> {
const { result, lease } = await self.acquireTextureVariant_(path, flipY !== false);
return self.textureLease_(lease, result);
},
noteAssetProblems(asset: string, problems: readonly string[]): void {
const path = self.resolveLoadPath_(asset);
const same = (self.assetProblems_.get(path) ?? []).join('\n') === problems.join('\n');
if (problems.length === 0) self.assetProblems_.delete(path);
else self.assetProblems_.set(path, [...problems]);
if (!same) self.assetProblemListener_?.(path, problems);
},
noteMaterialTexture(material: string, texture: string): void {
if (self.meshMaterials_.has(self.resolveLoadPath_(material)) || self.meshMaterials_.has(material)) {
self.meshTextures_.add(self.resolveLoadPath_(texture));
}
},
async acquireAsset<T>(type: string, ref: string): Promise<AssetLease<T>> {
return self.acquireTyped<T>(type, ref);
},
async loadText(path: string): Promise<string> {
return self.backend.fetchText(self.backend.resolveUrl(path));
},
async loadBinary(path: string): Promise<ArrayBuffer> {
return self.backend.fetchBinary(self.backend.resolveUrl(path));
},
async decodePixels(path: string) {
// The platform's one decode path: the runtime-injected pixel
// decoder when present (wechat / playable), else fetch→bitmap.
const decoder = self.textureLoader_.pixelDecoder;
if (decoder) return decoder(path, false);
return fetchDecodePixels(self.backend.resolveUrl(self.catalog.getBuildPath(path)));
},
async createTextureFromPixels(width, height, pixels, flipY) {
return self.textureLoader_.loadFromPixels(width, height, pixels, flipY, TextureContent.Retained);
},
async createOwnedTexture(width, height, pixels, flipY) {
return self.ownedTextureLease_(
await self.textureLoader_.loadFromPixels(width, height, pixels, flipY, TextureContent.Retained),
);
},
getAudio() {
return self.getAudio_();
},
getSpriteAnimation() {
return self.getSpriteAnimation_();
},
getLocalization() {
return self.getLocalization_();
},
};
return this.loadContext_;
}
}