Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

18.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { AddressableAssetType } from '../assetTypes';
import { indexTextureImportSettings, type ParsedTextureImportSettings } from './textureImportSettings';
import type { SpineCullingRect, SpineManifestContract } from './spineImportSettings';
import { contentHashOf } from './contentHash';
import { log } from '../util/logger';

const warnedNotPackaged = new Set<string>();
let probing = 0;

/**
 * Run `fn` asking about refs that may well not be packaged, without the warning
 * for each one that is not. A video asks whether the cook demuxed an audio track
 * beside it (`<video>.m4a`), and a target that plays the video whole, as the
 * mobile hosts do, has none: said as a missing asset, the question failed every
 * video example's boot on Android and iOS. Synchronous, so the window closes with it.
 */
export function probeRefs<T>(fn: () => T): T {
    probing++;
    try {
        return fn();
    } finally {
        probing--;
    }
}

/**
 * A project file the package does not carry, said once and with the reason —
 * otherwise the first anyone hears of it is a 404 from the loader. Only refs
 * that look like files: `builtin:` meshes, URLs and blobs are not the cook's.
 */
function warnNotPackaged(ref: string): void {
    if (probing > 0 || warnedNotPackaged.has(ref) || ref.includes(':') || !/\.[a-z0-9]{2,8}$/i.test(ref)) return;
    warnedNotPackaged.add(ref);
    log.warn('asset', `"${ref}" is not in this package. A build ships what its scenes reference, what the `
        + 'scripts name as a whole path in a string literal, and the folders asset-groups.json marks '
        + 'alwaysInclude — name the file whole in code, or mark its folder alwaysInclude.');
}

export type { AddressableAssetType };

/** Where a texture's small copy is, and how big it and the file are. */
export interface StreamTailInfo {
    path: string;
    size: number;
    width: number;
    height: number;
    fullWidth: number;
    fullHeight: number;
}

export interface AddressableManifestAsset {
    path: string;
    address?: string;
    type: AddressableAssetType;
    size: number;
    labels: string[];
    /**
     * Content hash of the built bytes (XXH64, see contentHash.ts), the asset's
     * *physical* identity.
     * Populated by the import pipeline. Lets the runtime dedupe by content and
     * treat `<contentHash>.<ext>` as an immutable, permanently-cacheable URL
     * (changing a file yields a new hash → a new URL, never a stale cache).
     */
    contentHash?: string;
    /** GPU compressed formats this asset was encoded for (e.g. ['astc-4x4','etc2-rgba8']). */
    compressedFormats?: string[];
    /** A small copy of a texture a mesh draws, which texture streaming fetches first (`path` is its build path). */
    streamTail?: StreamTailInfo;
    /**
     * How the texture is sampled and sliced — the runtime half of the `.meta`
     * importer block, parsed at cook time rather than shipped raw: a packaged
     * realm needs filter/wrap/sRGB and the 9-slice border, never the cook's own
     * settings (maxSize, compression format). Absent when the asset is not a
     * texture or its importer says nothing the renderer acts on.
     */
    textureImport?: ParsedTextureImportSettings;
    /**
     * A spine skeleton's culling promise: the rectangle, and the ATLAS it was
     * promised against as this manifest's own KEY, not a build locator.
     *
     * It ships rather than being re-derived, which would honour the promise
     * after a skeleton was re-pointed at another atlas.
     */
    spineImport?: SpineManifestContract;
    /**
     * Present when the export packed this asset with others into one file, which
     * a network build fetches once instead of one request per asset: `path` then
     * names no file of its own, and its bytes are `size` at `offset` in `file`.
     */
    pack?: AssetPackRef;
    metadata?: {
        atlas?: string;
        atlasPage?: number;
        atlasFrame?: { x: number; y: number; width: number; height: number };
        /** Page pixel size — with atlasFrame, what the runtime derives uv from. */
        atlasPageWidth?: number;
        atlasPageHeight?: number;
    };
}

/** Where a packed asset's bytes sit (see {@link AddressableManifestAsset.pack}). */
export interface AssetPackRef {
    /** The pack, as a path beside the manifest. */
    file: string;
    offset: number;
    size: number;
}

export interface AddressableManifestGroup {
    bundleMode: string;
    labels: string[];
    assets: Record<string, AddressableManifestAsset>;
}

export interface AddressableManifest {
    version: '2.0';
    /**
     * Build content revision — a stable hash over every asset's `contentHash`
     * (see {@link deriveManifestRevision}). Two builds share a revision iff they
     * ship byte-identical content under the same addressable keys, so a
     * changed / added / removed asset flips it. It is the fast gate for "is there
     * an update?"; the per-asset `contentHash` diff stays authoritative on WHAT
     * changed. Optional — absent on legacy manifests, where the diff falls back
     * to comparing contentHashes (or build paths) directly.
     */
    revision?: string;
    groups: Record<string, AddressableManifestGroup>;
}

/**
 * Stable content revision of a manifest: XXH64 over every asset's sorted
 * `<group>\t<key>\t<contentHash>` line. Deterministic and order-independent, so
 * two cooks of identical content produce the same string and any content / set
 * change flips it. A BUILD-TIME helper (rides {@link contentHashOf}'s
 * `TextEncoder`); the runtime reads the emitted `revision` field and never
 * recomputes it.
 */
export function deriveManifestRevision(manifest: AddressableManifest): string {
    const lines: string[] = [];
    for (const [groupName, group] of Object.entries(manifest.groups)) {
        for (const [key, asset] of Object.entries(group.assets)) {
            lines.push(`${groupName}\t${key}\t${asset.contentHash ?? ''}`);
        }
    }
    lines.sort();
    return contentHashOf(lines.join('\n'));
}

/**
 * Delivery mode for an addressable group — the single typed source of truth for
 * what was historically a bare `bundleMode: string` scattered across the cook /
 * export / runtime sides.
 * - `local`  — ships in the main package, loaded eagerly (current default; the
 *              value `exportWeChat` emits today).
 * - `lazy`   — ships in a subpackage (e.g. a WeChat 分包), loaded on demand.
 * - `remote` — fetched from a remote / CDN URL on demand.
 */
export type BundleMode = 'local' | 'lazy' | 'remote';

export const BUNDLE_MODES: readonly BundleMode[] = ['local', 'lazy', 'remote'];

/**
 * Normalize a wire `bundleMode` string to a known {@link BundleMode}. Unknown /
 * missing values map to `local` — the safe default: treated as part of the main
 * package so the asset is always present.
 */
export function normalizeBundleMode(mode: string | undefined | null): BundleMode {
    return mode != null && (BUNDLE_MODES as readonly string[]).includes(mode)
        ? (mode as BundleMode)
        : 'local';
}

/**
 * Queryable view over an {@link AddressableManifest}. The manifest JSON is the
 * wire format; this is the **runtime single source of truth** for group / label
 * / bundle-mode questions, so loaders and exporters never re-walk `groups` by
 * hand and never re-interpret the bare `bundleMode` string.
 */
/** Every way a manifest entry can be named — the spellings a ref may arrive as. */
function spellingsOf(key: string, path: string, address: string | undefined): string[] {
    const out: string[] = [];
    for (const spelling of [key, `@uuid:${key}`, path, address]) {
        if (!spelling) continue;
        out.push(spelling);
        if (!spelling.startsWith('/')) out.push(`/${spelling}`);
    }
    return out;
}

export class ManifestModel {
    private constructor(private readonly manifest: AddressableManifest) {}

    static fromJson(manifest: AddressableManifest): ManifestModel {
        return new ManifestModel(manifest);
    }

    private packs_: Map<string, AssetPackRef> | null = null;

    /** The pack holding the asset at build `path`, or null when it has a file of its own. */
    packOf(path: string): AssetPackRef | null {
        if (!this.packs_) {
            this.packs_ = new Map();
            for (const g of Object.values(this.manifest.groups)) {
                for (const a of Object.values(g.assets)) if (a.pack) this.packs_.set(a.path, a.pack);
            }
        }
        return this.packs_.get(path) ?? null;
    }

    /** The build paths each pack holds, by pack file. */
    packMembers(): Map<string, Set<string>> {
        const members = new Map<string, Set<string>>();
        for (const g of Object.values(this.manifest.groups)) {
            for (const a of Object.values(g.assets)) {
                if (!a.pack) continue;
                let set = members.get(a.pack.file);
                if (!set) members.set(a.pack.file, set = new Set());
                set.add(a.path);
            }
        }
        return members;
    }

    static empty(): ManifestModel {
        return new ManifestModel({ version: '2.0', groups: {} });
    }

    /** All group names, in manifest order. */
    groupNames(): string[] {
        return Object.keys(this.manifest.groups);
    }

    group(name: string): AddressableManifestGroup | null {
        return this.manifest.groups[name] ?? null;
    }

    /** Typed delivery mode of a group (unknown group → `local`). */
    bundleMode(name: string): BundleMode {
        return normalizeBundleMode(this.manifest.groups[name]?.bundleMode);
    }

    /** Group names whose delivery mode equals `mode`. */
    groupsByMode(mode: BundleMode): string[] {
        return this.groupNames().filter((n) => this.bundleMode(n) === mode);
    }

    /** Assets in a group (empty for an unknown group). */
    assetsInGroup(name: string): AddressableManifestAsset[] {
        const g = this.manifest.groups[name];
        return g ? Object.values(g.assets) : [];
    }

    /** Asset paths in a group. */
    assetPathsInGroup(name: string): string[] {
        return this.assetsInGroup(name).map((a) => a.path);
    }

    /** Every asset across all groups. */
    allAssets(): AddressableManifestAsset[] {
        const out: AddressableManifestAsset[] = [];
        for (const g of Object.values(this.manifest.groups)) {
            out.push(...Object.values(g.assets));
        }
        return out;
    }

    /** Every asset carrying its owning group name and record key — the iteration
     *  the hot-update diff walks (allAssets() drops both). */
    entries(): Array<{ group: string; key: string; asset: AddressableManifestAsset }> {
        const out: Array<{ group: string; key: string; asset: AddressableManifestAsset }> = [];
        for (const [group, g] of Object.entries(this.manifest.groups)) {
            for (const [key, asset] of Object.entries(g.assets)) {
                out.push({ group, key, asset });
            }
        }
        return out;
    }

    /**
     * Per-ref texture import settings for every asset that carries them — what a
     * packaged realm answers `RuntimeAssetSource.textureImportSettings` with, so
     * a shipped game samples and 9-slices exactly as the editor did.
     */
    textureImportLookup(): (ref: string) => ParsedTextureImportSettings | undefined {
        return indexTextureImportSettings(
            this.entries().map(({ key, asset }) => ({
                uuid: key,
                path: asset.path,
                address: asset.address,
                settings: asset.textureImport,
            })),
        );
    }

    /**
     * The culling contract this build ships for a spine PAIR, or undefined.
     *
     * Both refs, because there is no useful answer about a skeleton alone. The
     * atlas is compared as an IDENTITY — `@uuid:…`, a path and an address all
     * agree — so one the contract was not made against inherits nothing.
     */
    spineCullingLookup(): (skeleton: string, atlas: string) => SpineCullingRect | undefined {
        const contracts = new Map<string, SpineManifestContract>();
        const identity = new Map<string, string>();
        for (const { key, asset } of this.entries()) {
            for (const spelling of spellingsOf(key, asset.path, asset.address)) {
                identity.set(spelling, key);
                if (asset.spineImport) contracts.set(spelling, asset.spineImport);
            }
        }
        if (contracts.size === 0) return () => undefined;
        return (skeleton, atlas) => {
            const contract = contracts.get(skeleton);
            if (!contract) return undefined;
            // Identity settles it, and unknown is a no. `contract.atlas` is
            // already a key, so only the ref in hand is canonicalised.
            return identity.get(atlas) === contract.atlas ? contract.cullingBounds : undefined;
        };
    }

    /** The manifest's build content revision (see {@link deriveManifestRevision}),
     *  or null on a legacy manifest that predates the field. */
    revision(): string | null {
        return this.manifest.revision ?? null;
    }

    /** Assets carrying `label` across all groups, deduped by path. */
    assetsByLabel(label: string): AddressableManifestAsset[] {
        const seen = new Set<string>();
        const out: AddressableManifestAsset[] = [];
        for (const a of this.allAssets()) {
            if (a.labels.includes(label) && !seen.has(a.path)) {
                seen.add(a.path);
                out.push(a);
            }
        }
        return out;
    }

    /** Find an asset by its path or its address (null if absent). */
    findAsset(pathOrAddress: string): AddressableManifestAsset | null {
        for (const a of this.allAssets()) {
            if (a.path === pathOrAddress || a.address === pathOrAddress) return a;
        }
        return null;
    }

    // -------------------------------------------------------------------------
    // Resolution (uuid/address key → asset → build path)
    // -------------------------------------------------------------------------

    private keyIndex_: Map<string, AddressableManifestAsset> | null = null;
    private pathIndex_: Map<string, AddressableManifestAsset> | null = null;
    private remoteIndex_: { byRef: Map<string, string>; identity: Map<string, string> } | null = null;

    private indexes(): { byKey: Map<string, AddressableManifestAsset>; byPath: Map<string, AddressableManifestAsset> } {
        if (!this.keyIndex_ || !this.pathIndex_) {
            const byKey = new Map<string, AddressableManifestAsset>();
            const byPath = new Map<string, AddressableManifestAsset>();
            for (const g of Object.values(this.manifest.groups)) {
                for (const [key, asset] of Object.entries(g.assets)) {
                    // First write wins, mirroring the historical hand-built index
                    // (a uuid/path appearing in two groups keeps its first entry).
                    if (!byKey.has(key)) byKey.set(key, asset);
                    if (!byPath.has(asset.path)) byPath.set(asset.path, asset);
                    // The address (the asset's LOGICAL source path, kept when
                    // content-addressed staging renames the physical file) is a
                    // resolvable key too — path-style refs name it. Both the
                    // bare and the "/"-rooted spellings the cook may emit.
                    if (asset.address) {
                        if (!byKey.has(asset.address)) byKey.set(asset.address, asset);
                        const rooted = `/${asset.address}`;
                        if (!byKey.has(rooted)) byKey.set(rooted, asset);
                    }
                }
            }
            this.keyIndex_ = byKey;
            this.pathIndex_ = byPath;
        }
        return { byKey: this.keyIndex_, byPath: this.pathIndex_ };
    }

    /** Asset by its group-record key (the uuid in editor/WeChat manifests). */
    assetByKey(key: string): AddressableManifestAsset | null {
        return this.indexes().byKey.get(key) ?? null;
    }

    /** Asset by its build path. */
    assetByPath(path: string): AddressableManifestAsset | null {
        return this.indexes().byPath.get(path) ?? null;
    }

    /**
     * Build path of a `remote`-group asset by ANY of its keys — record key (uuid),
     * address (logical source path, bare and `/`-rooted), or build path — or null
     * when the ref is not a remote-delivered asset. Lets a resolver route scene
     * `@uuid` refs to remote assets through the CDN (so they hot-update with the
     * manifest), while local / lazy assets keep their normal resolution.
     */
    remoteAssetPath(ref: string): string | null {
        return this.remoteIndexes_().byRef.get(ref) ?? null;
    }

    /**
     * The stable name of the `remote`-group asset a ref names — its address,
     * else the key it is filed under. NOT interchangeable with
     * {@link remoteAssetPath}: a build path is content-addressed, so it names
     * one revision, while this is what every revision agrees on.
     */
    remoteAssetIdentity(ref: string): string | null {
        return this.remoteIndexes_().identity.get(ref) ?? null;
    }

    /** Both remote indexes, built together from one walk. */
    private remoteIndexes_(): { byRef: Map<string, string>; identity: Map<string, string> } {
        if (!this.remoteIndex_) {
            const byRef = new Map<string, string>();
            const identity = new Map<string, string>();
            for (const group of Object.values(this.manifest.groups)) {
                if (normalizeBundleMode(group.bundleMode) !== 'remote') continue;
                for (const [key, asset] of Object.entries(group.assets)) {
                    const name = asset.address ?? key;
                    for (const ref of [key, asset.path, ...(asset.address ? [asset.address, `/${asset.address}`] : [])]) {
                        byRef.set(ref, asset.path);
                        identity.set(ref, name);
                    }
                }
            }
            this.remoteIndex_ = { byRef, identity };
        }
        return this.remoteIndex_;
    }

    /**
     * Resolve a serialized asset ref (a uuid, an address, or a path) to its
     * build path, falling back to the ref itself. The single manifest→path
     * resolution the shipped runtimes use, and the last word on the name: a
     * build path is whatever the cook staged the file as.
     */
    resolvePath(ref: string): string {
        const { byKey, byPath } = this.indexes();
        const entry = byKey.get(ref) ?? byPath.get(ref);
        if (!entry) warnNotPackaged(ref);
        return entry ? entry.path : ref;
    }
}