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.

41.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    scene.ts
 * @brief   Scene loading utilities
 */

import { World } from '../ecs/world';
import { Entity, INVALID_ENTITY } from '../types';
import { upgradeEntityComponents } from './legacyComponents';
import { isPrefabEntry, type SceneEntry } from './sceneEntry';
import { canDefer, cutToRoot, isDeferredInstance, rootOnly, rootOverrides, type DeferredRecord, VARIANT_KEY } from '../prefab/deferred';
import { expandVirtualRequested, registerDeferredInstances } from './deferredInstances';
import { validateScene } from './validateScene';
import { getComponent, Name, Camera, RuntimeOnly } from '../ecs/component';
import { deepClone } from '../util/deepClone';
import { discoverSceneAssets } from '../asset/discoverAssets';
import { AssetScope } from '../asset/AssetLease';
import type { PrefabResult } from '../asset/AssetLoader';
import { requireResourceManager } from '../wasm/resourceManager';
import { validateComponentData, formatValidationErrors } from '../util/validation';
import { log } from '../util/logger';
import { prepareSpawnOwnership, type PreparedSpawnOwnership } from '../prefab/preparedAssetOwnership';
import { ESTELLA_SCENE_GENERATOR } from '../util/provenance';
import {
    expandEntry,
    preloadNestedPrefabs,
    migratePrefabData,
    type PrefabData,
    type PrefabInstanceEntry,
    type ProcessedEntity,
} from '../prefab/index';

// =============================================================================
// Types
// =============================================================================

export interface SceneEntityData {
    id: number;
    name: string;
    parent: number | null;
    children: number[];
    components: SceneComponentData[];
    visible?: boolean;
}

export interface SceneComponentData {
    type: string;
    data: Record<string, unknown>;
}

export interface SliceBorder {
    left: number;
    right: number;
    top: number;
    bottom: number;
}

export interface TextureMetadata {
    version: string;
    type: 'texture';
    sliceBorder: SliceBorder;
}

export interface SceneData {
    /**
     * Format version: one integer that only counts up. Files written before it
     * became an integer carry a `"major.minor"` string, which
     * {@link migrateSceneData} normalizes — read it through
     * {@link parseSceneFormatVersion}, never by comparing it directly.
     */
    version: number | string;
    name: string;
    /** Origin tag of the engine that wrote this scene (see provenance.ts). */
    generator?: string;
    entities: SceneEntityData[];
    textureMetadata?: Record<string, TextureMetadata>;
    /**
     * Set by {@link expandScenePrefabs} on the scene it answers, never written to a file: the virtual instances it left as roots
     * alone, and what each is made from. The loader hands them to the world once the entities exist.
     */
    deferredInstances?: DeferredRecord[];
}

export interface LoadedSceneAssets {
    texturePaths: Set<string>;
    materialHandles: Set<number>;
    fontPaths: Set<string>;
    spineKeys: Set<string>;
    /**
     * The receipts the preload produced, handed to whoever owns the scene.
     * Present means the owner releases through these and must not also release
     * the same assets by path — that is the double free this replaces.
     */
    scope?: import('../asset/AssetLease').AssetScope;
}

/** Progress during a scene load, in assets: how many are done of how many.
 *  @beta */
export type SceneLoadProgressCallback = (loaded: number, total: number) => void;

export type MissingAssetCallback = (missing: import('../asset/Assets').MissingAsset[]) => void;

export interface SceneLoadOptions {
    assets?: import('../asset/Assets').Assets;
    assetBaseUrl?: string;
    collectAssets?: LoadedSceneAssets;
    onProgress?: SceneLoadProgressCallback;
    /**
     * Invoked once during load with the list of asset refs that could not
     * be loaded (unresolved UUID or fetch failure). Fires even if the list
     * is empty — callers that want "missing asset" UI wire this up.
     */
    onMissingAssets?: MissingAssetCallback;
    /**
     * If true, throw after preloading when any asset is missing; the
     * scene is not spawned. Default is false (legacy behaviour: missing
     * assets get handle 0, scene loads anyway).
     */
    abortOnMissingAssets?: boolean;
    /**
     * Authored ids this document may reference that live in another one — the
     * persistent rows a streamed cell is allowed to name. Absent = a reference
     * outside the document resolves to nothing, which is what it always did.
     */
    externalEntities?: ReadonlyMap<number, Entity>;
    /**
     * Where a load's time went, phase by phase. Most of it runs between frames —
     * off every system timer there is — so a profiler watching the frame loop
     * sees the cost and cannot say what it was.
     *
     * A name may be dotted, and a dot means containment: `spawn.components` is
     * part of `spawn`, so a reader sums the roots and never the whole list.
     */
    onPhase?: ScenePhaseSink;
}

/**
 * Where a load's time went. Dotted names nest; see {@link SceneLoadOptions.onPhase}.
 *
 * @experimental
 */
export type ScenePhaseSink = (phase: string, ms: number) => void;

export class MissingAssetsError extends Error {
    readonly missing: import('../asset/Assets').MissingAsset[];
    constructor(missing: import('../asset/Assets').MissingAsset[]) {
        super(`Scene load aborted: ${missing.length} asset(s) missing`);
        this.name = 'MissingAssetsError';
        this.missing = missing;
    }
}

// =============================================================================
// Asset Field Types
// =============================================================================

/**
 * The asset kinds a component field may hold — a closed set, because each one
 * names a registered loader. Adding one means adding the loader too.
 *
 * @public
 */
export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'sound-event' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'scriptgraph' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment' | 'probeVolume' | 'prefab';

// =============================================================================
// Component Query Helpers (read from self-describing ComponentDef)
// =============================================================================

export function getComponentAssetFields(componentType: string): string[] {
    const comp = getComponent(componentType);
    if (!comp) return [];
    const fields: string[] = [];
    for (const { field } of comp.assetFields) {
        fields.push(field);
    }
    if (comp.skeletalFields) {
        fields.push(comp.skeletalFields.skeletonField);
        fields.push(comp.skeletalFields.atlasField);
    }
    return fields;
}

export function getComponentAssetFieldDescriptors(
    componentType: string,
): readonly { field: string; type: AssetFieldType }[] {
    return getComponent(componentType)?.assetFields ?? [];
}

/** The skeleton/atlas pair a component carries, and whose runtime it belongs to. */
export function getComponentSkeletalFieldDescriptor(
    componentType: string,
): { skeletonField: string; atlasField: string; runtime: string } | null {
    return getComponent(componentType)?.skeletalFields ?? null;
}

// =============================================================================
// Entity Reference Remapping
// =============================================================================

/**
 * Resolve a document's entity references to live entities.
 *
 * `external` answers for authored ids that live in ANOTHER document — the rows a
 * streamed cell is allowed to name in the persistent world. An id neither map
 * knows is cleared, never left as a number that names a different entity.
 */
export function remapEntityFields(
    compData: SceneComponentData,
    entityMap: Map<number, Entity>,
    external?: ReadonlyMap<number, Entity>,
): void {
    const comp = getComponent(compData.type);
    if (!comp || comp.entityFields.length === 0) return;
    const data = compData.data as Record<string, unknown>;
    const remap = (editorId: unknown): unknown => {
        if (typeof editorId !== 'number' || editorId === INVALID_ENTITY) return editorId;
        const runtimeId = entityMap.get(editorId) ?? external?.get(editorId);
        if (runtimeId === undefined) {
            log.warn(
                'scene',
                `Entity reference not found: ${compData.type}.${field} ` +
                `references entity ${editorId} which does not exist`,
            );
        }
        return runtimeId !== undefined ? runtimeId : INVALID_ENTITY;
    };
    // A field can name ONE entity or a list of them (a skin's joints). A list
    // that skipped this kept the document's own ids, which name other entities
    // at runtime — the reference silently resolves to the wrong thing.
    let field = '';
    for (field of comp.entityFields) {
        const value = data[field];
        data[field] = Array.isArray(value) ? value.map(remap) : remap(value);
    }
}

// =============================================================================
// Component serialization codecs (out-of-band data)
// =============================================================================

/**
 * Hook for a component whose full state does not fit the plain field record —
 * e.g. TilemapLayer's tile chunks live in a C++ blob. Registered by the owning
 * plugin (see tilemapPlugin) so the generic (de)serializer carries no
 * component-specific knowledge.
 */
export interface SceneComponentCodec {
    /** Serialize: write out-of-band state into the plain record. */
    exportData?(entity: number, data: Record<string, unknown>): void;
    /**
     * Out-of-band field keys. Stripped from `data` before validation/insert
     * (so the component insert doesn't choke on them) and passed to
     * {@link importData} after insert.
     */
    outOfBandFields?: readonly string[];
    /** Deserialize: reapply out-of-band state after the component is inserted. */
    importData?(entity: number, outOfBand: Record<string, unknown>): void;
}

const sceneComponentCodecs = new Map<string, SceneComponentCodec>();
const worldComponentCodecs = new WeakMap<World, Map<string, SceneComponentCodec>>();

/** @internal A world's component codecs take precedence over host defaults. */
export function registerWorldSceneComponentCodec(world: World, type: string, codec: SceneComponentCodec): () => void {
    let codecs = worldComponentCodecs.get(world);
    if (!codecs) worldComponentCodecs.set(world, codecs = new Map());
    codecs.set(type, codec);
    return () => {
        if (codecs.get(type) === codec) codecs.delete(type);
        if (codecs.size === 0) worldComponentCodecs.delete(world);
    };
}

export type SceneExportFilter = (entity: Entity, component: string, data: Record<string, unknown>) => void;

const worldExportFilters = new WeakMap<World, Set<SceneExportFilter>>();

/** @internal */
export function registerWorldSceneExportFilter(world: World, filter: SceneExportFilter): () => void {
    let filters = worldExportFilters.get(world);
    if (!filters) worldExportFilters.set(world, filters = new Set());
    filters.add(filter);
    return () => {
        filters.delete(filter);
        if (filters.size === 0) worldExportFilters.delete(world);
    };
}

function sceneComponentCodec(world: World, type: string): SceneComponentCodec | undefined {
    return worldComponentCodecs.get(world)?.get(type) ?? sceneComponentCodecs.get(type);
}

/** Register a custom (de)serializer for a component type. Idempotent. */
export function registerSceneComponentCodec(type: string, codec: SceneComponentCodec): void {
    sceneComponentCodecs.set(type, codec);
}

/**
 * What a component carries beside its fields — a MeshRenderer's inline `geometry`:
 * saved with the scene by its codec, but no field, so no inspector or set_field
 * reaches it. Empty for a component without such data.
 */
export function sceneOutOfBandFields(type: string): readonly string[] {
    return sceneComponentCodecs.get(type)?.outOfBandFields ?? declaredOutOfBand.get(type) ?? [];
}

const declaredOutOfBand = new Map<string, readonly string[]>();

/**
 * @internal Say which data a component carries beside its fields before its codec
 * is installed (codecs install with their plugin, which a tool asking about a
 * component may never build).
 */
export function declareSceneOutOfBandFields(type: string, fields: readonly string[]): void {
    declaredOutOfBand.set(type, fields);
}

// =============================================================================
// Prefab instance entries (runtime play == ship)
// =============================================================================

/** True if any scene entry is a prefab instance (cheap gate before expansion). */
export function sceneHasPrefabEntries(scene: SceneData): boolean {
    return (scene.entities as SceneEntry[]).some(isPrefabEntry);
}

/** Resolves a prefab asset ref to its PrefabData, or null when unresolvable. */
export type PrefabAssetResolver = (ref: string) => Promise<PrefabData | null>;

const toSceneEntityData = (e: ProcessedEntity): SceneEntityData => ({
    id: e.id,
    name: e.name,
    parent: e.parent,
    children: e.children,
    components: e.components,
    visible: e.visible,
});

/**
 * Expand every prefab-instance entry in a scene into ordinary entity records,
 * leaving non-prefab entities untouched. Each instance is flattened via
 * `expandEntry` (the shared prefab core) with its nested prefabs preloaded, so
 * the result is a plain SceneData ready for migration + spawn. Async because
 * resolving prefab (and nested-prefab) assets is async; an unresolvable prefab
 * drops that one instance with a warning rather than aborting the whole scene.
 */
export async function expandScenePrefabs(
    scene: SceneData,
    loadPrefab: PrefabAssetResolver,
    options?: { expandVirtual?: boolean },
): Promise<SceneData> {
    const expandVirtual = options?.expandVirtual ?? expandVirtualRequested();
    const entries = scene.entities as SceneEntry[];
    // Allocate fresh ids for expanded internals above every id already in the
    // file, so they never collide with non-prefab entities or instance roots
    // (which keep their stable scene id across save/load).
    let nextId = 0;
    for (const e of entries) nextId = Math.max(nextId, e.id);
    const allocateId = () => ++nextId;

    const out: SceneEntityData[] = [];
    const deferred: DeferredRecord[] = [];
    for (const entry of entries) {
        if (!isPrefabEntry(entry)) {
            out.push(entry);
            continue;
        }
        if (expandVirtual && entry.overrides.some((o) => o.type === 'metadata_set' && o.metadataKey === VARIANT_KEY)) continue;
        const raw = await loadPrefab(entry.prefab);
        if (!raw) {
            log.warn('scene', `Prefab instance "${entry.prefab}" could not be resolved; instance skipped`);
            continue;
        }
        const prefab = migratePrefabData(raw).data;
        // Preload nested prefabs into a cache so the sync flatten resolver never
        // misses — `flattenPrefab` throws on an unresolved nested ref.
        const cache = new Map<string, PrefabData>();
        try {
            await preloadNestedPrefabs(
                prefab,
                async (ref) => {
                    const d = await loadPrefab(ref);
                    if (!d) throw new Error(`nested prefab "${ref}" not found`);
                    return migratePrefabData(d).data;
                },
                cache,
            );
        } catch (e) {
            log.warn('scene', `Prefab instance "${entry.prefab}" has an unresolved nested prefab; instance skipped (${e})`);
            continue;
        }
        // A virtual instance is made as its root alone (see prefab/deferred.ts); instances inside it are left to whoever opens it.
        const virtual = !expandVirtual && isDeferredInstance(prefab, entry.overrides) && canDefer(entry.overrides, prefab)
            && entry.added.length === 0 && entry.removed.length === 0;
        const stub = virtual ? rootOnly(prefab) : null;
        const { entities: expanded, unresolved: unresolvedAll } = expandEntry(
            stub ?? prefab, stub ? { ...entry, overrides: rootOverrides(prefab, entry.overrides) } : entry, allocateId,
            (ref) => cache.get(ref) ?? null, expandVirtual ? undefined : deferred);
        const entities = virtual && !stub ? cutToRoot(expanded, entry.id) : expanded;
        const unresolved = virtual ? [] : unresolvedAll;
        if (virtual) deferred.push({ id: entry.id, prefab: entry.prefab, overrides: entry.overrides.map((o) => ({ ...o })) });
        if (unresolved.length > 0) {
            const targets = [...new Set(unresolved.map((o) => o.prefabEntityId))].join(', ');
            log.warn('scene', `Prefab instance "${entry.prefab}" (entity ${entry.id}) overrides `
                + `${unresolved.length} thing(s) on ${targets}, which the prefab has no entity for; `
                + 'those overrides change nothing');
        }
        for (const pe of entities) out.push(toSceneEntityData(pe));
    }
    return deferred.length > 0 ? { ...scene, entities: out, deferredInstances: deferred } : { ...scene, entities: out };
}

// =============================================================================
// Scene Migration — versioned, idempotent, non-mutating (mirrors prefab/migrate)
// =============================================================================

/**
 * Current scene format version — bump by one per migration step below.
 *
 * An integer, not semver: this number only has to answer "older, current, or
 * newer", and dotted ones cannot. `parseFloat` sorts "1.10" below "1.2".
 *
 * 2: `Light2D` and `Mesh2D` renamed to `Light` and `MeshRenderer`. An engine
 *    from before the rename reads the new names as components it has never
 *    heard of and drops them, which is a scene that loads and has no lights —
 *    so it must refuse the file instead, and the version is what tells it to.
 * 3: the flat physics components took the `2D` suffix the 3D ones already had
 *    (`RigidBody` → `RigidBody2D`, the four colliders, `CharacterController`).
 *    Same reasoning as 2, and worse here: an older engine drops the bodies and
 *    loads a level whose floor nothing collides with.
 * 4: the flat joints took the 3D set's words, which are also the industry's
 *    (`RevoluteJoint2D` → `HingeJoint2D`, prismatic → slider, weld → fixed).
 *    Same reasoning again: dropped joints load a machine whose parts fall apart.
 */
export const SCENE_FORMAT_VERSION = 4;

export interface SceneMigrationResult {
    /** A migrated *copy* — the input is never mutated. */
    data: SceneData;
    /** True if any legacy shape was upgraded (callers may prompt a re-save). */
    migrated: boolean;
    /** Retired engine components dropped, by name — an editor says which it
     *  upgraded away; a runtime load has no one to tell. */
    retired: string[];
    fromVersion: number;
    toVersion: number;
}

/**
 * The format version of a scene, however it was written. Everything from before
 * the integer scheme is format 1, so its leading digits are the whole answer.
 * Unreadable reads as 1, not 0: a scene with no version predates having one.
 */
export function parseSceneFormatVersion(v: unknown): number {
    if (typeof v === 'number') return Number.isInteger(v) && v > 0 ? v : 1;
    if (typeof v === 'string') {
        const leading = /^\s*(\d+)/.exec(v);
        if (leading) return Math.max(1, Number(leading[1]));
    }
    return 1;
}

/**
 * Component types retired by an engine upgrade. A scene authored before the
 * retirement still serializes them; {@link migrateSceneData} drops them so the
 * loader never warns "Unknown component type" on dead data, and the editor tells
 * them apart from genuinely-unknown project components (which it preserves). The
 * behaviour they encoded lives on in successor systems — the retired UI
 * StateMachine/StateVisuals pair is superseded by UIController($interaction) +
 * UIGear, which the widget prefabs now carry.
 */
export { RETIRED_COMPONENT_TYPES } from './legacyComponents';

/**
 * Components an engine upgrade renamed, old name to new. Exported because a
 * rename is not a loss, and anything comparing a released file against what
 * opening it yields has to be able to tell the two apart from one table rather
 * than a copy of it.
 */
export { RENAMED_COMPONENT_TYPES } from './legacyComponents';

/**
 * Upgrade a SceneData to the current format. Total + idempotent: already-current
 * data returns `migrated: false`; migrations are shape-driven so they no-op on
 * current scenes. Rejects data newer than this engine. Returns a deep copy, so
 * loading never mutates the caller's object (snapshots can be reloaded).
 */
export function migrateSceneData(raw: SceneData): SceneMigrationResult {
    const fromVersion = checkSceneFormat(raw);
    // Public inputs remain caller-owned. Internal builders can hand over their
    // fresh private records to the same normalization without copying them twice.
    return migrateOwnedSceneData(JSON.parse(JSON.stringify(raw)) as SceneData, fromVersion);
}

function checkSceneFormat(raw: SceneData): number {
    if (!raw || typeof raw !== 'object' || !Array.isArray(raw.entities)) {
        throw new Error('Scene data must have an "entities" array');
    }
    const fromVersion = parseSceneFormatVersion(raw.version);
    if (fromVersion > SCENE_FORMAT_VERSION) {
        throw new Error(
            `Scene format version ${fromVersion} is newer than this engine supports ` +
            `(${SCENE_FORMAT_VERSION}); upgrade the engine to load it.`,
        );
    }

    return fromVersion;
}

function migrateOwnedSceneData(data: SceneData, fromVersion = checkSceneFormat(data)): SceneMigrationResult {
    let migrated = false;
    const retired = new Set<string>();
    for (const entity of data.entities) {
        // Prefab-instance entries carry no `components` to migrate; the async
        // loader expands them first, so any seen here belong to the sync path
        // and are left untouched (spawnAndLoadEntities warns + skips them).
        if (isPrefabEntry(entity)) continue;
        if (upgradeEntityComponents(entity, retired)) migrated = true;
    }

    data.version = SCENE_FORMAT_VERSION;
    return { data, migrated, retired: [...retired], fromVersion, toVersion: SCENE_FORMAT_VERSION };
}

// =============================================================================
// Scene Loader
// =============================================================================

/**
 * Findings that make a scene mean something other than what it says, where
 * loading is worse than refusing: a repeated id sends every reference to it to
 * whichever entity came last, and a parent cycle has no hierarchy to build.
 * Everything else still loads — a lost parent leaves an entity at the root.
 */
const UNLOADABLE_SCENE: ReadonlySet<string> = new Set(['duplicate-id', 'parent-cycle']);

/** Refuse a scene the loader cannot honour; report the rest and carry on. */
function checkLoadable(sceneData: SceneData): void {
    const diags = validateScene(sceneData);
    if (diags.length === 0) return;
    const fatal = diags.filter((d) => UNLOADABLE_SCENE.has(d.code));
    for (const d of diags) {
        if (!fatal.includes(d)) log.warn('scene', `${d.code}: ${d.message}`);
    }
    if (fatal.length > 0) {
        throw new Error(
            `Scene "${sceneData.name}" cannot be loaded as written:\n`
            + fatal.map((d) => `  ${d.code}: ${d.message}`).join('\n'),
        );
    }
}

function spawnAndLoadEntities(
    world: World, sceneData: SceneData, external?: ReadonlyMap<number, Entity>,
    onPhase?: ScenePhaseSink,
): Map<number, Entity> {
    // One clock reading per component rather than two: the end of one write is
    // the start of the next, so attribution costs a call and not a pair.
    let mark = onPhase ? performance.now() : 0;
    const since = (): number => {
        const now = performance.now();
        const elapsed = now - mark;
        mark = now;
        return elapsed;
    };
    checkLoadable(sceneData);
    if (onPhase) onPhase('spawn.validate', since());
    const entityMap = new Map<number, Entity>();
    try {
        for (const entityData of sceneData.entities) {
            if (entityData.visible === false) continue;
            // A prefab-instance entry reaching here means the synchronous path was
            // used on an unexpanded prefab scene — it has no spawnable components.
            // Skip it (loadSceneWithAssets is the supported prefab-scene path).
            if (isPrefabEntry(entityData)) {
                log.warn('scene', 'Prefab-instance entry skipped in synchronous load; use loadSceneWithAssets to load prefab scenes');
                continue;
            }
            const entity = world.spawn();
            entityMap.set(entityData.id, entity);
            world.insert(entity, Name, { value: entityData.name });
        }
        if (onPhase) onPhase('spawn.entities', since());

        // By component TYPE, because "component writes" is a rename of the total
        // and not an answer: which writes reach a subsystem, and which are field
        // validation, is the difference between a mechanism and a number.
        const byType = onPhase ? new Map<string, number>() : null;
        for (const entityData of sceneData.entities) {
            if (entityData.visible === false) continue;
            if (isPrefabEntry(entityData)) continue;
            const entity = entityMap.get(entityData.id)!;
            for (const compData of entityData.components) {
                remapEntityFields(compData, entityMap, external);
                loadComponent(world, entity, compData, entityData.name);
                if (byType) byType.set(compData.type, (byType.get(compData.type) ?? 0) + since());
            }
        }
        if (onPhase && byType) {
            let total = 0;
            for (const [type, ms] of byType) {
                total += ms;
                onPhase(`spawn.components.${type}`, ms);
            }
            onPhase('spawn.components', total);
        }

        for (const entityData of sceneData.entities) {
            if (entityData.parent !== null) {
                const entity = entityMap.get(entityData.id);
                const parentEntity = entityMap.get(entityData.parent);
                if (entity !== undefined && parentEntity !== undefined) {
                    world.setParent(entity, parentEntity);
                }
            }
        }
        if (onPhase) onPhase('spawn.hierarchy', since());
    } catch (e) {
        for (const entity of entityMap.values()) {
            try { world.despawn(entity); } catch { /* ignore cleanup errors */ }
        }
        throw e;
    }

    return entityMap;
}

export function loadSceneData(
    world: World, sceneData: SceneData, external?: ReadonlyMap<number, Entity>,
    onPhase?: ScenePhaseSink,
): Map<number, Entity> {
    const began = onPhase ? performance.now() : 0;
    const { data } = migrateSceneData(sceneData);
    // Named because it is a surprise: migration deep-clones the whole document
    // so the caller's data is never mutated, and on a streamed cell that clone
    // is paid at the door — after preparation already had the bytes in hand.
    if (onPhase) onPhase('spawn.migrate', performance.now() - began);
    return spawnAndLoadEntities(world, data, external, onPhase);
}

/**
 * Reset the world to a previously-captured scene: despawn every current entity,
 * then reload `sceneData`. Used for editor play-state isolation (snapshot before
 * Play via {@link serializeScene}, restore on Stop), level restart, etc. Because
 * {@link loadSceneData} no longer mutates its input, the same snapshot can be
 * restored repeatedly. Entity ids change; the returned map is
 * snapshot-id → new entity for callers that need to remap references/selection.
 */
export function resetWorldTo(world: World, sceneData: SceneData): Map<number, Entity> {
    // getAllEntities returns a fresh array, so despawning as we go is safe; the
    // valid() guard tolerates despawn cascading to children.
    for (const entity of world.getAllEntities()) {
        if (world.valid(entity)) world.despawn(entity);
    }
    return loadSceneData(world, sceneData);
}

export async function loadSceneWithAssets(
    world: World,
    sceneData: SceneData,
    options?: SceneLoadOptions
): Promise<Map<number, Entity>> {
    const timed = scenePhaseRunner(options?.onPhase);
    // Expand prefab-instance entries first (via the same flattenPrefab core the
    // editor uses) so migration + asset resolution + spawn all operate on plain
    // entities — this is how a saved prefab scene achieves play == ship. The
    // prefab's own asset refs are resolved by the regular preload below.
    let scene = sceneData;
    if (options?.assets && sceneHasPrefabEntries(scene)) {
        const assets = options.assets;
        const sources = new AssetScope();
        try {
            scene = await timed('prefab', () => expandScenePrefabs(scene, async (ref) => {
                try {
                    const lease = sources.add(await assets.acquireTyped<PrefabResult>('prefab', ref));
                    return (lease.value.data as PrefabData) ?? null;
                } catch (e) {
                    log.warn('scene', `Failed to load prefab "${ref}": ${e}`);
                    return null;
                }
            }));
        } finally {
            // Expansion copies source JSON into scene records. Only those records'
            // asset dependencies outlive this phase, acquired by the preload below.
            sources.releaseAll();
        }
    }
    // Migrate up-front to a private copy; asset resolution + spawn all operate
    // on it, so the caller's SceneData is never mutated.
    const { data } = migrateSceneData(scene);
    const deferred = scene.deferredInstances;
    const entities = await loadSceneAssetsAndSpawn(world, data, options, timed);
    registerDeferredInstances(world, deferred, entities);
    return entities;
}

/**
 * Consume fresh private scene records from an internal builder. The builder must
 * have copied every mutable component and override value before handing them
 * over. Validation, migrations, asset resolution and spawning are shared with
 * the public scene loader; only its caller-protection copy is already paid.
 * @internal
 */
export async function loadOwnedSceneWithAssets(
    world: World, scene: SceneData, options?: SceneLoadOptions,
): Promise<Map<number, Entity>> {
    const timed = scenePhaseRunner(options?.onPhase);
    const { data } = migrateOwnedSceneData(scene);
    return loadSceneAssetsAndSpawn(world, data, options, timed);
}

function scenePhaseRunner(onPhase?: ScenePhaseSink) {
    return async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {
        if (!onPhase) return run();
        const began = performance.now();
        try { return await run(); } finally { onPhase(phase, performance.now() - began); }
    };
}

async function loadSceneAssetsAndSpawn(
    world: World, data: SceneData, options: SceneLoadOptions | undefined,
    timed: <T>(phase: string, run: () => Promise<T> | T) => Promise<T>,
): Promise<Map<number, Entity>> {
    let ownership: PreparedSpawnOwnership | undefined;
    let releasePreload: (() => void) | undefined;
    let spawned: Map<number, Entity> | undefined;
    try {
        if (options?.assets) {
            const assets = options.assets;
            const result = await timed('assets', () => assets.preloadSceneAssets(data, options.onProgress));
            if (!options.collectAssets && assets.entityScopes) {
                releasePreload = () => result.scope.releaseAll();
                ownership = prepareSpawnOwnership(data, result, assets.entityScopes, assets.resolveRef.bind(assets))?.();
            }
            if (options.onMissingAssets) {
                options.onMissingAssets(result.missing);
            }
            if (options.abortOnMissingAssets && result.missing.length > 0) {
                throw new MissingAssetsError(result.missing);
            }
            assets.resolveSceneAssetPaths(data, result);
            applyTextureMetadata(data, result.textureHandles);
            if (options.collectAssets) {
                // The receipts MOVE to the owner (absorb, not add): two scopes each
                // holding every receipt leaves "which one releases it" unanswered.
                // Materials keep their handle set too, but the RELEASE rides the scope.
                options.collectAssets.scope?.absorb(result.scope);
                for (const handle of result.materialHandles.values()) {
                    if (handle) options.collectAssets.materialHandles.add(handle);
                }
            }
        }
        const entities = await timed('spawn', () => {
            spawned = spawnAndLoadEntities(world, data, options?.externalEntities, options?.onPhase);
            return spawned;
        });
        ownership?.attach(world, entities);
        options?.assets?.trackSceneAssetReferences(data, entities);
        return entities;
    } catch (error) {
        if (spawned) for (const entity of spawned.values()) {
            try { if (world.valid(entity)) world.despawn(entity); }
            catch { /* A cleanup callback must not hide the original load failure. */ }
        }
        throw error;
    } finally {
        ownership?.release();
        releasePreload?.();
    }
}

function applyTextureMetadata(sceneData: SceneData, textureHandles: Map<string, number>): void {
    if (!sceneData.textureMetadata) return;
    const rm = requireResourceManager();
    for (const [path, metadata] of Object.entries(sceneData.textureMetadata)) {
        const handle = textureHandles.get(path);
        if (handle && metadata.sliceBorder) {
            const b = metadata.sliceBorder;
            rm.setTextureMetadata(handle, b.left, b.right, b.top, b.bottom);
        }
    }
}

export function loadComponent(world: World, entity: Entity, compData: SceneComponentData, entityName?: string): void {
    // Legacy-format normalization happens once up-front in migrateSceneData;
    // by here compData is already current-shape.
    const comp = getComponent(compData.type);
    if (!comp) {
        const context = entityName ? ` on entity "${entityName}"` : '';
        log.warn('scene', `Unknown component type: ${compData.type}${context}`);
        return;
    }

    // Strip out-of-band fields (e.g. TilemapLayer's tile-chunk blob) before
    // validation/insert so the component insert doesn't choke on them; the
    // registered codec replays them once the component is in.
    const codec = sceneComponentCodec(world, compData.type);
    let outOfBand: Record<string, unknown> | undefined;
    if (codec?.outOfBandFields?.length) {
        for (const field of codec.outOfBandFields) {
            if (field in compData.data) {
                (outOfBand ??= {})[field] = compData.data[field];
                delete compData.data[field];
            }
        }
    }

    // Asset-ref fields validate leniently: their serialized string ref and runtime
    // numeric handle are both legal (a Tiled-imported Tilemap's `source: 0` == "none").
    const context = entityName ? ` (entity "${entityName}")` : '';
    const errors = validateComponentData(compData.type, comp._default as Record<string, unknown>, compData.data, comp.assetFields);
    if (errors.length > 0) {
        // Salvage, not sacrifice: deserialized data is the one input the strict
        // storage validators must not veto wholesale — drop the invalid fields so
        // their defaults apply and the REST of the component still loads. Without
        // this the insert below throws and one stale string in a saved scene
        // bricks the whole scene load.
        for (const err of errors) {
            const root = err.field in compData.data ? err.field : err.field.split('.')[0];
            delete compData.data[root];
        }
        // A converted Cocos script component carries what its scene serialized, including fields the class has since dropped; Cocos ignores
        // those without a word, and so does this.
        const stale = compData.type.startsWith('Cocos.') && errors.every((e) => e.actual === 'unknown field');
        const report = stale ? log.debug : log.warn;
        report.call(
            log,
            'scene',
            `${formatValidationErrors(compData.type + context, errors)}\n  → invalid fields dropped, their defaults apply (fix the scene file to silence this)`
        );
    }
    try {
        world.insert(entity, comp, compData.data);
    } catch (err) {
        // Defense in depth: a deeper boundary rejection costs THIS component, not
        // the scene.
        log.error(
            'scene',
            `component "${compData.type}"${context} failed to insert — skipped: ${err instanceof Error ? err.message : String(err)}`
        );
        return;
    }

    if (codec?.importData && outOfBand) {
        codec.importData(entity as unknown as number, outOfBand);
    }
}

// =============================================================================
// Scene Serializer
// =============================================================================

// Components that describe the scene graph structure itself — name, parent
// pointers, children lists, and derived world-transform caches. They are
// reconstructed on load from the SceneEntityData {name, parent, children}
// fields rather than from the components list, so we omit them here.
const STRUCTURAL_COMPONENTS = new Set(['Name', 'Parent', 'Children', 'WorldTransform']);

/**
 * One entity's serializable component payloads — the per-entity primitive
 * serializeScene is built from, also the spawn-replication payload (RC11):
 * skips structural + transient components, folds out-of-band codec state in.
 * Round-trips through {@link loadComponent}.
 */
export function serializeEntityComponents(world: World, entity: Entity): SceneComponentData[] {
    const entityNum = entity as unknown as number;
    const components: SceneComponentData[] = [];
    for (const typeName of world.getComponentTypes(entity)) {
        if (STRUCTURAL_COMPONENTS.has(typeName)) continue;
        const comp = getComponent(typeName);
        if (!comp) continue;
        // Runtime-only components (per-frame pointer/drag/hover state) never
        // persist — their systems rebuild them each frame. See ComponentMetadata.transient.
        if (comp.transient) continue;
        const data = world.tryGet(entity, comp);
        if (data === null) continue;
        // tryGet returns a fresh object for builtins (convertFromWasm) but the LIVE
        // stored object for script components — clone the latter so the snapshot
        // doesn't alias running-world state (and exportData below can't mutate it).
        const payload = (comp._builtin ? data : deepClone(data)) as Record<string, unknown>;
        // Components with out-of-band state (e.g. TilemapLayer chunks) fold
        // it into the record via their registered codec.
        sceneComponentCodec(world, typeName)?.exportData?.(entityNum, payload);
        for (const filter of worldExportFilters.get(world) ?? []) filter(entity, typeName, payload);
        components.push({
            type: typeName,
            data: payload,
        });
    }
    return components;
}

/**
 * Walks the live world and produces a SceneData that round-trips through
 * loadSceneData. Editors call this on save; external tools (prefab extract,
 * diff, CLI export) can reuse the same primitive.
 *
 * Parent/child links are collapsed into the entity record's parent+children
 * fields; the Parent and Children components themselves are omitted from
 * the components array so loadSceneData's setParent pass is the single
 * source of truth for hierarchy.
 */
export function serializeScene(world: World, sceneName = 'scene'): SceneData {
    const parentDef = getComponent('Parent');
    // RuntimeOnly entities are world-only projections their systems re-derive
    // (Tilemap source layers, tile colliders); excluding them up front also
    // keeps them out of every parent/children list below.
    const allEntities = world.getAllEntities().filter((e) => !world.has(e, RuntimeOnly));

    const parentOf = new Map<number, number>();
    if (parentDef) {
        for (const e of allEntities) {
            const parentComp = world.tryGet(e, parentDef) as { entity: number } | null;
            if (parentComp && parentComp.entity !== undefined) {
                parentOf.set(e as unknown as number, parentComp.entity);
            }
        }
    }

    // Derived from the parent map already built above: one pass, no second read per entity.
    const childrenOf = new Map<number, number[]>();
    for (const [child, parent] of parentOf) {
        let arr = childrenOf.get(parent);
        if (!arr) {
            arr = [];
            childrenOf.set(parent, arr);
        }
        arr.push(child);
    }

    const entities: SceneEntityData[] = [];
    for (const entity of allEntities) {
        const entityNum = entity as unknown as number;

        const nameComp = world.tryGet(entity, Name) as { value: string } | null;
        const name = nameComp?.value ?? `Entity_${entityNum}`;

        const components = serializeEntityComponents(world, entity);

        entities.push({
            id: entityNum,
            name,
            parent: parentOf.get(entityNum) ?? null,
            children: childrenOf.get(entityNum) ?? [],
            components,
        });
    }

    return {
        version: SCENE_FORMAT_VERSION,
        name: sceneName,
        generator: ESTELLA_SCENE_GENERATOR,
        entities,
    };
}

export function updateCameraAspectRatio(world: World, aspectRatio: number): void {
    const cameraEntities = world.getEntitiesWithComponents([Camera]);
    for (const entity of cameraEntities) {
        const camera = world.get(entity, Camera);
        if (camera) {
            camera.aspectRatio = aspectRatio;
            world.insert(entity, Camera, camera);
        }
    }
}

export function findEntityByName(world: World, name: string): Entity | null {
    return world.findEntityByName(name);
}