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.

14.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
export type AssetContentType = 'json' | 'text' | 'binary' | 'image' | 'audio';

export type AddressableAssetType =
    | 'texture' | 'material' | 'spine' | 'bitmap-font' | 'font'
    | 'prefab' | 'json' | 'text' | 'binary' | 'audio';

export type EditorAssetType =
    | 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'
    | 'dragonbones-atlas' | 'dragonbones-skeleton'
    | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'
    | 'tilemap' | 'tileset' | 'timeline' | 'mesh'
    | 'unknown';

export interface AssetTypeEntry {
    extensions: string[];
    /**
     * Full lower-case name endings claiming this type, checked BEFORE extensions
     * because they are the more specific claim. For a format whose files are told
     * apart by convention rather than suffix — DragonBones ships `_ske.json`
     * beside `_tex.json`, and `.json` alone cannot see the difference.
     */
    suffixes?: string[];
    contentType: AssetContentType;
    editorType: EditorAssetType;
    addressableType: AddressableAssetType | null;
    wechatPackInclude: boolean;
    hasTransitiveDeps: boolean;
}

const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [
    { extensions: ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'], contentType: 'image', editorType: 'texture', addressableType: 'texture', wechatPackInclude: false, hasTransitiveDeps: false },
    // GPU-compressed texture container (Basis/KTX2). Decoded straight to a
    // compressed GPU format at runtime; large, so it stays out of the WeChat
    // main package (remote CDN, content-addressed).
    // wechatPackInclude: WeChat's fs denies package reads of unlisted custom
    // extensions — KTX2 textures are fs-read (transcoded), not image-decoded.
    { extensions: ['ktx2'], contentType: 'binary', editorType: 'texture', addressableType: 'texture', wechatPackInclude: true, hasTransitiveDeps: false },
    // A picture's source, drawn into a texture where it is loaded (asset/textureRecipe.ts).
    { extensions: ['esimage'], contentType: 'json', editorType: 'texture', addressableType: 'texture', wechatPackInclude: true, hasTransitiveDeps: false },
    // A sound's or a piece of music's source, named where a clip goes: a clip to whatever loads it (see asset/audioRecipe.ts).
    { extensions: ['essound', 'esmusic'], contentType: 'json', editorType: 'audio', addressableType: 'audio', wechatPackInclude: true, hasTransitiveDeps: false },
    { extensions: ['mp3', 'wav', 'ogg', 'aac', 'flac', 'm4a', 'webm'], contentType: 'audio', editorType: 'audio', addressableType: 'audio', wechatPackInclude: false, hasTransitiveDeps: false },
    // Video container, streamed + decoded by the video system (HTMLVideoElement
    // on web). `webm` stays with audio above to avoid the ambiguity; a .webm
    // video is disambiguated by its `.meta` type. Cooked/copied as binary.
    { extensions: ['mp4', 'm4v', 'mov'], contentType: 'binary', editorType: 'video', addressableType: 'binary', wechatPackInclude: false, hasTransitiveDeps: false },
    // MPEG-1 video for the wasm decode path (WeChat / headless). `.esv` is the
    // cook's codec-tagged output; `.mpg` an authored source. fs-read by the
    // decoder, so packaged WeChat reads need the pack-include whitelist.
    { extensions: ['mpg', 'mpeg', 'esv'], contentType: 'binary', editorType: 'video', addressableType: 'binary', wechatPackInclude: true, hasTransitiveDeps: false },
    { extensions: ['esmaterial'], contentType: 'json', editorType: 'material', addressableType: 'material', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['esshader'], contentType: 'text', editorType: 'shader', addressableType: null, wechatPackInclude: false, hasTransitiveDeps: false },
    { extensions: ['atlas'], contentType: 'text', editorType: 'spine-atlas', addressableType: 'binary', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['skel'], contentType: 'binary', editorType: 'spine-skeleton', addressableType: 'spine', wechatPackInclude: true, hasTransitiveDeps: true },
    // DragonBones. The atlas has transitive deps — its `imagePath` names a PNG no
    // component references, so without that flag the cook ships the atlas and culls
    // the image it points at, and the export 404s a texture at runtime.
    { extensions: ['dbbin'], suffixes: ['_ske.json'], contentType: 'binary', editorType: 'dragonbones-skeleton', addressableType: 'binary', wechatPackInclude: true, hasTransitiveDeps: false },
    { extensions: [], suffixes: ['_tex.json'], contentType: 'text', editorType: 'dragonbones-atlas', addressableType: 'binary', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['json'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: false, hasTransitiveDeps: false },
    // Input map (defineInputMap / loadInputMapAsset) — data-driven key/gamepad bindings.
    { extensions: ['inputmap'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
    { extensions: ['bmfont'], contentType: 'json', editorType: 'bitmap-font', addressableType: 'bitmap-font', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['fnt'], contentType: 'text', editorType: 'bitmap-font', addressableType: 'bitmap-font', wechatPackInclude: true, hasTransitiveDeps: true },
    // Outline fonts a game SHIPS (Text.font). Unlike a bitmap font these have no
    // page texture, so no transitive deps — the file IS the asset, handed whole
    // to the platform's text stack.
    { extensions: ['ttf', 'otf', 'woff', 'woff2'], contentType: 'binary', editorType: 'font', addressableType: 'font', wechatPackInclude: true, hasTransitiveDeps: false },
    { extensions: ['esprefab'], contentType: 'json', editorType: 'prefab', addressableType: 'prefab', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['esscene'], contentType: 'json', editorType: 'scene', addressableType: null, wechatPackInclude: false, hasTransitiveDeps: false },
    // GPU geometry (MeshAssetLoader). Its own channel table makes it
    // self-describing, so it names no other asset; the source it was imported
    // from (.gltf/.glb/.fbx) is not shipped and is deliberately absent here.
    { extensions: ['esmesh'], contentType: 'binary', editorType: 'mesh', addressableType: 'binary', wechatPackInclude: true, hasTransitiveDeps: false },
    { extensions: ['esanim'], contentType: 'json', editorType: 'anim-clip', addressableType: null, wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['tmj'], contentType: 'json', editorType: 'tilemap', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    // Tileset palette (TilesetAssetLoader). Fs-read as JSON at runtime — so it
    // needs the WeChat pack whitelist — and it references an atlas texture by
    // @uuid (transitive dep).
    { extensions: ['estileset'], contentType: 'json', editorType: 'tileset', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['estimeline'], contentType: 'json', editorType: 'timeline', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['esaudioevent'], contentType: 'json', editorType: 'sound-event', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    // World rules (WorldRulesAssetLoader): biomes, recipes and layers as data, naming the meshes and materials they place by path.
    { extensions: ['esworld'], contentType: 'json', editorType: 'world-rules', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    // Terrain layers (TerrainLayerAssetLoader): one kind of ground, naming the albedo, normal and mask textures it is drawn with.
    { extensions: ['esterrainlayer'], contentType: 'json', editorType: 'terrain-layer', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    { extensions: ['esterrain'], contentType: 'json', editorType: 'terrain-tiles', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    // Locale string table (LocaleAssetLoader → Localization.addCatalog) — one locale per file.
    { extensions: ['eslocale'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
    // State machine (registerFsm / FsmAssetLoader) — data-driven FSM definition.
    { extensions: ['esfsm'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
    // Animation controller (AnimatorControllerDef) — data-driven sprite-anim state machine.
    { extensions: ['esanimator'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
    // Behavior tree (registerBt / BtAssetLoader) — data-driven BT definition.
    { extensions: ['esbt'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
    // Script graph (registerScriptGraph / ScriptGraphAssetLoader) — visual logic.
    { extensions: ['esgraph'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
    // Prefiltered environment: nine irradiance coefficients inline, plus the path
    // of the octahedral atlas they were baked beside — hence the transitive dep,
    // without which the cook ships the document and culls the image it is half of.
    { extensions: ['esenv'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },
    // Baked probe grid: the same nine coefficients an `.esenv` carries, at every
    // point of a grid instead of once. No transitive dep — a volume names no image.
    { extensions: ['esprobes'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
];

const MIME_MAP: Record<string, string> = {
    png: 'image/png',
    jpg: 'image/jpeg',
    jpeg: 'image/jpeg',
    gif: 'image/gif',
    webp: 'image/webp',
    svg: 'image/svg+xml',
    bmp: 'image/bmp',
    ktx2: 'image/ktx2',
    mp3: 'audio/mpeg',
    wav: 'audio/wav',
    ogg: 'audio/ogg',
    aac: 'audio/aac',
    m4a: 'audio/mp4',
    flac: 'audio/flac',
    webm: 'audio/webm',
    mp4: 'video/mp4',
    m4v: 'video/x-m4v',
    mov: 'video/quicktime',
    mpg: 'video/mpeg',
    mpeg: 'video/mpeg',
    esv: 'video/mpeg',
    json: 'application/json',
    atlas: 'text/plain',
    skel: 'application/octet-stream',
    esmaterial: 'application/json',
    esshader: 'text/plain',
    esprefab: 'application/json',
    esmesh: 'application/octet-stream',
    esanim: 'application/json',
    estimeline: 'application/json',
    estileset: 'application/json',
    eslocale: 'application/json',
    esfsm: 'application/json',
    esanimator: 'application/json',
    esbt: 'application/json',
    esenv: 'application/json',
    esprobes: 'application/json',
    bmfont: 'application/json',
    fnt: 'text/plain',
};

const extToEntry = new Map<string, AssetTypeEntry>();
const allExtensions = new Set<string>();

for (const entry of ASSET_TYPE_REGISTRY) {
    for (const ext of entry.extensions) {
        extToEntry.set(ext, entry);
        allExtensions.add(ext);
    }
}

/**
 * A host whose packer refuses a custom suffix takes the file under `.bin`
 * (exportMiniGame's restage). What it IS is still whatever the real suffix says,
 * so read through that wrapper — but only when a known extension is under it, or
 * a file genuinely named `foo.bin` would read as one with no extension at all.
 */
function extractExtension(extensionOrPath: string): string {
    const lower = extensionOrPath.toLowerCase();
    const last = (v: string): string => {
        const dot = v.lastIndexOf('.');
        return dot >= 0 ? v.substring(dot + 1) : v;
    };

    if (lower.endsWith('.bin')) {
        const under = last(lower.slice(0, -'.bin'.length));
        if (allExtensions.has(under)) return under;
    }
    return last(lower);
}

/**
 * A path with the restage `.bin` wrapper removed, when it wraps an extension this
 * registry knows. Readers that care about a specific format ask this rather than
 * spelling both paths — one place learns what a restaged file looks like.
 */
export function unwrapRestagedPath(path: string): string {
    const lower = path.toLowerCase();
    if (!lower.endsWith('.bin')) return lower;
    const under = lower.slice(0, -'.bin'.length);
    const dot = under.lastIndexOf('.');
    const ext = dot >= 0 ? under.substring(dot + 1) : under;
    return allExtensions.has(ext) ? under : lower;
}

export function getAssetTypeEntry(extensionOrPath: string): AssetTypeEntry | undefined {
    // Suffix first: `foo_ske.json` is a DragonBones skeleton, and letting `.json`
    // answer would classify it as whatever that extension maps to.
    const lower = extensionOrPath.toLowerCase();
    for (const entry of ASSET_TYPE_REGISTRY) {
        if (entry.suffixes?.some((s) => lower.endsWith(s))) return entry;
    }
    return extToEntry.get(extractExtension(extensionOrPath));
}

export function getEditorType(path: string): EditorAssetType {
    return getAssetTypeEntry(path)?.editorType ?? 'unknown';
}

export function getAddressableType(path: string): AddressableAssetType | null {
    return getAssetTypeEntry(path)?.addressableType ?? null;
}

export function getAddressableTypeByEditorType(editorType: string): AddressableAssetType | null {
    for (const entry of ASSET_TYPE_REGISTRY) {
        if (entry.editorType === editorType) {
            return entry.addressableType;
        }
    }
    if (editorType === 'text') return 'text';
    if (editorType === 'binary') return 'binary';
    return 'binary';
}

export function isKnownAssetExtension(ext: string): boolean {
    return allExtensions.has(ext.toLowerCase());
}

export function getAllAssetExtensions(): Set<string> {
    return allExtensions;
}

export function looksLikeAssetPath(value: unknown): value is string {
    if (typeof value !== 'string') return false;
    if (!value.includes('/')) return false;
    return isKnownAssetExtension(extractExtension(value));
}

export function getCustomExtensions(): string[] {
    const result: string[] = [];
    for (const entry of ASSET_TYPE_REGISTRY) {
        if (entry.wechatPackInclude) {
            for (const ext of entry.extensions) {
                result.push(`.${ext}`);
            }
        }
    }
    return result;
}

export function getWeChatPackOptions(): Array<{ type: string; value: string }> {
    return getCustomExtensions().map(ext => ({ type: 'suffix', value: ext }));
}

export function getAssetMimeType(ext: string): string | undefined {
    return MIME_MAP[ext.toLowerCase()];
}

export function isCustomExtension(path: string): boolean {
    const entry = getAssetTypeEntry(path);
    return entry?.wechatPackInclude ?? false;
}