Skip to content

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

7.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    discoverAssets.ts
 * @brief   Unified asset discovery from scene/prefab data.
 *
 * Each component may reference assets in three ways: a custom
 * `discoverAssets` callback, declared `assetFields`, or paired
 * `skeletalFields`. This module walks a SceneData and buckets every
 * such ref by asset type. A `discoverAssets` callback is authoritative:
 * when present, `assetFields` are not walked for discovery (they still
 * drive the editor's asset pickers and ref rewrites) — the callback may
 * deliberately exclude values, e.g. FSM/BT agents skip plain
 * code-registered names that only look like asset refs.
 *
 * Refs in serialized data may be either a concrete path
 * (`"assets/player.png"`, legacy) or a UUID reference
 * (`"@uuid:xxxxxxxx-..."`, produced by the meta-driven pipeline).
 * An optional `refResolver` callback translates a ref to its
 * current path before bucketing. Without a resolver the ref is
 * passed through unchanged — works for legacy scenes that still
 * store paths directly.
 */

import { getComponent } from '../ecs/component';
import type { SceneData, AssetFieldType } from '../scene/scene';

export interface SpineAssetRef {
    skeleton: string;
    atlas: string;
}

/** A skeleton/atlas pair, whichever runtime poses it. */
export type SkeletalAssetRef = SpineAssetRef;

export interface SceneAssetRefs {
    byType: Map<string, Set<string>>;
    /**
     * The same buckets keyed by the RAW serialized ref (pre-resolution).
     * Loaders whose registry is keyed by what the COMPONENT carries (anim
     * clips: `SpriteAnimator.clip` / Animator states hold the serialized ref)
     * must be driven by the raw ref, so load-time aliasing can bind the raw
     * ref to the resolved registration — a realm whose resolver returns
     * absolute URLs would otherwise register under keys no component uses.
     */
    rawByType: Map<string, Set<string>>;
    /**
     * Resolved path → the RAW ref it came from (first spelling wins; several refs
     * can name one asset). Lets a caller that must bucket by resolved path — the
     * handle maps are keyed that way — still load through the authored ref, which
     * is the spelling per-asset lookups (texture import settings) are keyed by.
     */
    rawFor: Map<string, string>;
    /**
     * Skeleton/atlas pairs posed by SPINE. Split from {@link dragonBones} because
     * the two are loaded by different runtimes: a pair handed to the wrong one is
     * parsed by a parser that cannot read it, and fails as "unsupported version"
     * rather than as the routing mistake it is.
     */
    spines: SkeletalAssetRef[];
    /** Skeleton/atlas pairs posed by DragonBones. */
    dragonBones: SkeletalAssetRef[];
    /**
     * Refs seen during discovery that could not be resolved to a path
     * (e.g. unknown UUID). Callers surface this to the user so missing
     * assets don't silently turn into texture handle 0.
     */
    unresolved: string[];
    /** Resolved paths of the textures a MeshRenderer draws directly (its texture and normal map): what texture streaming may start small. */
    meshTextures: Set<string>;
    /** Resolved paths of the materials a MeshRenderer draws with: their textures may start small too. */
    meshMaterials: Set<string>;
}

/** Turns a raw serialized ref into a concrete path (or null if unknown). */
export type RefResolver = (ref: string) => string | null;

export function discoverSceneAssets(
    sceneData: SceneData,
    refResolver?: RefResolver,
): SceneAssetRefs {
    const byType = new Map<string, Set<string>>();
    const rawByType = new Map<string, Set<string>>();
    const rawFor = new Map<string, string>();
    const spines: SkeletalAssetRef[] = [];
    const dragonBones: SkeletalAssetRef[] = [];
    // One set across both runtimes: the key is the pair, and the same pair cannot
    // belong to two runtimes.
    const skeletalKeys = new Set<string>();
    const unresolved: string[] = [];
    const meshTextures = new Set<string>();
    const meshMaterials = new Set<string>();

    const resolve = (raw: string): string | null => {
        const r = refResolver ? refResolver(raw) : raw;
        if (r == null || r === '') {
            unresolved.push(raw);
            return null;
        }
        return r;
    };

    const bucket = (map: Map<string, Set<string>>, type: string, value: string): void => {
        let set = map.get(type);
        if (!set) {
            set = new Set();
            map.set(type, set);
        }
        set.add(value);
    };

    const addAsset = (type: string, raw: string): void => {
        const path = resolve(raw);
        if (path == null) return;
        bucket(byType, type, path);
        bucket(rawByType, type, raw);
        if (!rawFor.has(path)) rawFor.set(path, raw);
    };

    for (const entityData of sceneData.entities) {
        if (entityData.visible === false) continue;
        // A prefab-instance entry carries no inline `components` (it holds a prefab
        // ref plus overrides); its assets are discovered when the prefab is expanded
        // by loadSceneWithAssets, not from here. Skipping it also guards the loop
        // against `components: undefined` — the discovery pass runs on the raw scene,
        // before expansion, in the runtime and scene-manager preload paths.
        if (!Array.isArray(entityData.components)) continue;

        for (const compData of entityData.components) {
            const comp = getComponent(compData.type);
            if (!comp) continue;

            const data = compData.data as Record<string, unknown>;

            if (compData.type === 'MeshRenderer') {
                for (const [field, into] of [['texture', meshTextures], ['normalMap', meshTextures], ['material', meshMaterials]] as const) {
                    const raw = data[field];
                    const at = typeof raw === 'string' && raw ? (refResolver ? refResolver(raw) : raw) : null;
                    if (at) into.add(at);
                }
            }

            if (comp.discoverAssets) {
                for (const ref of comp.discoverAssets(data)) {
                    if (typeof ref.path === 'string' && ref.path) {
                        addAsset(ref.type, ref.path);
                    }
                }
            } else {
                for (const desc of comp.assetFields) {
                    const value = data[desc.field];
                    if (typeof value === 'string' && value) {
                        addAsset(desc.type, value);
                    }
                }
            }

            if (comp.skeletalFields) {
                const skelRaw = data[comp.skeletalFields.skeletonField] as string;
                const atlasRaw = data[comp.skeletalFields.atlasField] as string;
                if (skelRaw && atlasRaw) {
                    const skel = resolve(skelRaw);
                    const atlas = resolve(atlasRaw);
                    if (skel != null && atlas != null) {
                        const key = `${skel}:${atlas}`;
                        if (!skeletalKeys.has(key)) {
                            skeletalKeys.add(key);
                            // An unnamed runtime is Spine: the field predates the
                            // second runtime, so that is what a component without
                            // one has always meant.
                            const bucket = comp.skeletalFields.runtime === 'dragonbones' ? dragonBones : spines;
                            bucket.push({ skeleton: skel, atlas });
                        }
                    }
                }
            }
        }
    }

    return { byType, rawByType, rawFor, spines, dragonBones, unresolved, meshTextures, meshMaterials };
}

export function getAssetPathsByType(refs: SceneAssetRefs, type: AssetFieldType): Set<string> {
    return refs.byType.get(type) ?? new Set();
}