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.

10.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    worldSnapshot.ts
 * @brief   A running world as an inspector shows it: the shallow tree, and one
 *          entity with its values — from the editor's Play realm and from a
 *          device alike.
 */
import type { App } from '../app/app';
import type { World } from '../ecs/world';
import { getComponent, renderableComponents, type AnyComponentDef } from '../ecs/component';
import { getComponentAssetFieldDescriptors } from '../scene/scene';
import { Assets } from '../asset/AssetPlugin';
import { UINode, UIDisplay } from '../ui/core/ui-node';
import { sceneOriginOf } from '../scene/sceneOrigins';

/** Kept as the tree's own shape (name, parent, children) rather than as rows. */
const STRUCTURAL = new Set(['Name', 'Parent', 'Children', 'WorldTransform']);

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

export interface SnapshotEntity {
    id: number;
    name: string;
    parent: number | null;
    children: number[];
    /** Types only in the tree; values only for the entity asked for. */
    components: SnapshotComponent[];
    /** Whether it has something to hide, and whether it is hidden. */
    hideable?: boolean;
    hidden?: boolean;
    /** The id of the document entity it was loaded from, for the entry scene's. */
    src?: number;
}

export interface WorldSnapshot {
    tree: { version: '1.0'; name: 'live'; entities: SnapshotEntity[] } | null;
    selected: SnapshotEntity | null;
}

export interface WorldSnapshotOptions {
    /** The scene whose entities carry their document id (`src`). */
    entryScene?: string;
    /** Turns an asset's load path into the one its reader knows it by. */
    assetPath?: (path: string) => string | null;
}

/** Authoring inspection omits transient state; runtime diagnostics may request
 * it explicitly. The tree's own structural fields remain separate. */
export function inspectableTypes(world: World, entity: number, includeTransient = false): string[] {
    return filterInspectableTypes(world.getComponentTypes(entity as never), includeTransient);
}

function filterInspectableTypes(types: string[], includeTransient = false): string[] {
    return types.filter((t) => {
        if (STRUCTURAL.has(t)) return false;
        const def = getComponent(t);
        return !!def && (includeTransient || !def.transient);
    });
}

/**
 * Rewrite handle-valued asset fields to the load paths behind them. A World stores
 * handles; an inspector speaks refs, and a handle shown raw reads as an empty slot.
 * Handles nobody can name pass through untouched.
 */
export function translateAssetHandles(
    components: readonly SnapshotComponent[],
    pathForHandle: (kind: string, handle: number) => string | null,
): SnapshotComponent[] {
    return components.map(({ type, data }) => {
        let out: Record<string, unknown> | null = null;
        for (const d of getComponentAssetFieldDescriptors(type)) {
            const v = data[d.field];
            if (typeof v !== 'number' || v === 0) continue;
            const path = pathForHandle(d.type, v);
            if (path !== null) (out ??= { ...data })[d.field] = path;
        }
        return out ? { type, data: out } : { type, data };
    });
}

/**
 * @p app's world: the tree when @p withTree (O(entities), so a caller polling one
 * entity's values skips it), and @p selectedId's values when given.
 */
export function worldSnapshot(
    app: App, selectedId: number | null, withTree: boolean, opts: WorldSnapshotOptions = {},
): WorldSnapshot {
    const world = app.world;
    if (selectedId != null && !world.valid(selectedId as never)) selectedId = null;
    if (!withTree && selectedId == null) return { tree: null, selected: null };
    const nameDef = getComponent('Name');
    const parentDef = getComponent('Parent');
    const childrenDef = getComponent('Children');
    const ownerDef = getComponent('SceneOwner');
    const all = withTree ? world.getAllEntities() : [];
    const treeTypes = withTree ? world.getComponentTypesBatch(all) : null;
    const detailTypes = !withTree && selectedId != null ? world.getComponentTypes(selectedId as never) : null;
    let parentReader: ReturnType<World['resolveGetter']> | undefined;
    const parentValue = (entity: number, types: string[]): number | undefined => {
        if (!parentDef || !types.includes(parentDef._name)) return undefined;
        if (parentReader === undefined) parentReader = world.resolveGetter(parentDef);
        // Membership comes from the current core, not the SDK's hierarchy cache.
        // Only the scalar escapes a reader that may borrow its component value.
        const p = (parentReader ? parentReader(entity as never) : world.get(entity as never, parentDef)) as { entity?: number } | null;
        return p?.entity;
    };

    const parentOf = new Map<number, number>();
    const childrenOf = new Map<number, number[]>();
    if (!withTree && selectedId != null && childrenDef) {
        const parent = parentValue(selectedId, detailTypes!);
        if (parent !== undefined) parentOf.set(selectedId, parent);
        // Native hierarchy writers can move children without updating the SDK's
        // membership cache. Ask the current core before reading this relation.
        const hasChildren = world.resolveHas(childrenDef);
        let c: { entities?: number[] } | null = null;
        if (!hasChildren) {
            c = world.tryGet(selectedId as never, childrenDef) as { entities?: number[] } | null;
        } else if (hasChildren(selectedId as never)) {
            const read = world.resolveGetter(childrenDef, 'retained');
            c = (read ? read(selectedId as never) : world.tryGet(selectedId as never, childrenDef)) as { entities?: number[] } | null;
        }
        if (c?.entities?.length) {
            // Children is maintained with Parent. The inspector's order is the
            // world's storage order, which can differ from attachment order.
            const members = new Set(c.entities);
            childrenOf.set(selectedId, world.getAllEntities().filter(e => members.has(e)));
        }
    } else if (parentDef) {
        const entities = withTree ? all : world.getAllEntities();
        const types = treeTypes ?? world.getComponentTypesBatch(entities);
        for (let i = 0; i < entities.length; i++) {
            const parent = parentValue(entities[i], types[i]);
            if (parent !== undefined) parentOf.set(entities[i], parent);
        }
        for (const [child, parent] of parentOf) (childrenOf.get(parent) ?? childrenOf.set(parent, []).get(parent)!).push(child);
    }

    const nameOf = (e: number): string =>
        (nameDef ? (world.tryGet(e as never, nameDef) as { value?: string } | null)?.value : undefined) ?? `Entity_${e}`;
    const renderers = renderableComponents();
    const visibilityReaders = new Map<AnyComponentDef, (entity: number) => unknown>();
    const visibilityOf = (e: number, types: string[]): Pick<SnapshotEntity, 'hideable' | 'hidden'> => {
        const source = types.includes(UINode._name) ? UINode : renderers.find((comp) => types.includes(comp._name));
        if (!source) return {};
        let read = visibilityReaders.get(source);
        if (!read) {
            const getter = world.resolveGetter(source);
            read = getter ? (entity) => getter(entity as never) : (entity) => world.get(entity as never, source);
            visibilityReaders.set(source, read);
        }
        // Only the flag escapes: direct getters borrow their component value.
        const field = source === UINode ? 'display' : source.renderableField!;
        const value = read(e) as Record<string, unknown> | null;
        const data = value && value[field] !== undefined ? value : world.get(e as never, source) as Record<string, unknown>;
        const hidden = source === UINode ? data.display === UIDisplay.None : data[field] === false;
        return { hideable: true, hidden };
    };
    // Only the entry scene's ids name documents an editor has open.
    const srcOf = (e: number): number | undefined => {
        if (opts.entryScene === undefined) return undefined;
        const owner = ownerDef ? (world.tryGet(e as never, ownerDef) as { scene?: string } | null) : null;
        if ((owner?.scene ?? '') !== opts.entryScene) return undefined;
        return sceneOriginOf(app, e as never);
    };
    const shape = (id: number, components: SnapshotComponent[], types: string[]): SnapshotEntity => {
        const src = srcOf(id);
        return {
            id, name: nameOf(id), parent: parentOf.get(id) ?? null, children: childrenOf.get(id) ?? [],
            components, ...visibilityOf(id, types), ...(src === undefined ? {} : { src }),
        };
    };

    let selectedTypes: string[] | null = null;
    const tree = withTree
        ? {
            version: '1.0' as const, name: 'live' as const,
            entities: all.map((e, index) => {
                const id = e as never as number;
                const types = treeTypes![index];
                if (id === selectedId) selectedTypes = types;
                return shape(id, filterInspectableTypes(types).map((type) => ({ type, data: {} })), types);
            }),
        }
        : null;

    let selected: SnapshotEntity | null = null;
    if (selectedId != null) {
        const types = selectedTypes ?? detailTypes ?? world.getComponentTypes(selectedId as never);
        const raw = filterInspectableTypes(types)
            .map((type) => {
                const def = getComponent(type);
                const data = def ? world.tryGet(selectedId as never, def) : null;
                return data ? { type, data: data as Record<string, unknown> } : null;
            })
            .filter((c): c is SnapshotComponent => !!c);
        const assets = app.hasResource(Assets) ? app.getResource(Assets) : null;
        const components = translateAssetHandles(raw, (kind, handle) => {
            const p = assets?.pathForHandle(kind, handle) ?? null;
            return p === null ? null : (opts.assetPath ? opts.assetPath(p) : p);
        });
        selected = shape(selectedId, components, types);
    }
    return { tree, selected };
}