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.

6.0 KB
Raw Blame
import type { DeferredRecord } from './deferred';
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
export interface ComponentData {
    type: string;
    data: Record<string, unknown>;
}

/**
 * Per-entity identity inside a prefab file.
 *
 * The string is opaque — UUIDs for editor-authored prefabs, stringified
 * integers for migrated legacy files. Stability matters more than format:
 * once an entity has been assigned a `PrefabEntityId`, the editor must
 * never reassign or reuse it for the lifetime of the prefab, otherwise
 * existing instance overrides will silently apply to the wrong target.
 */
export type PrefabEntityId = string;

/**
 * Reserved separator that composes a flattened entity's HIERARCHICAL address.
 *
 * A nested prefab's entities are namespaced by the slot they were mounted
 * through, so `flattenPrefab` yields `slotId/…/localId` for anything reached
 * across a nesting boundary (top-level entities keep their bare id). This makes
 * the stable `prefabEntityId` on a flattened `ProcessedEntity` globally unique
 * within one instance — even when the same prefab is mounted in several sibling
 * slots. Authored `prefabEntityId`s must not contain this character.
 */
export const PREFAB_ADDRESS_SEP = '/';

export interface PrefabData {
    version: string;
    name: string;
    rootEntityId: PrefabEntityId;
    entities: PrefabEntityData[];
    /**
     * If set, this prefab inherits from another prefab. The variant's own
     * `entities` list may **override** existing base entries (matched by
     * `prefabEntityId`) and **add** new entities; `overrides` is applied
     * on top of the merged result.
     */
    basePrefab?: string;
    overrides?: PrefabOverride[];
}

export interface PrefabEntityData {
    prefabEntityId: PrefabEntityId;
    name: string;
    parent: PrefabEntityId | null;
    children: PrefabEntityId[];
    components: ComponentData[];
    visible: boolean;
    /**
     * Editor/tooling state that survives prefab round-trip. Not consumed by
     * the runtime engine — the runtime instantiation path drops this. The
     * editor uses it to round-trip per-entity metadata such as asset refs
     * (`asset:Comp.field` → uuid) and selection markers.
     */
    metadata?: Record<string, unknown>;
    nestedPrefab?: NestedPrefabRef;
}

export interface NestedPrefabRef {
    prefabPath: string;
    overrides: PrefabOverride[];
}

/**
 * Override types applied to an entity in an instantiated prefab.
 *
 * - `property`          — patch one field of one component.
 *                         Requires: componentType, propertyName, value.
 * - `name`              — change the entity's name. Requires: value (string).
 * - `visibility`        — change the entity's visibility. Requires: value (boolean).
 * - `parent`            — re-parent a prefab-origin entity within the instance.
 *                         Requires: value = the new parent's stable
 *                         `PrefabEntityId`, or `null` for "under the instance
 *                         root". Structural: applied by `expandInstance` /
 *                         `applyDeltaToSource` (which own the id space), not by
 *                         `applyOverrides`. The instance root is never re-parented
 *                         this way — its attach point is the instance entry's own
 *                         `parent`.
 * - `component_added`   — add a component **only if not already present**
 *                         (idempotent insert). Requires: componentData.
 *                         Use this for variants that want to *augment* the
 *                         base without silently stomping existing data.
 * - `component_replaced`— upsert: replace the component's data if the
 *                         component already exists, or insert it if not.
 *                         Requires: componentData. Use this when you
 *                         explicitly want to override the base's copy.
 * - `component_removed` — delete the component if present.
 *                         Requires: componentType.
 * - `metadata_set`      — set or replace one metadata key. Requires:
 *                         metadataKey, value (any JSON-serialisable).
 *                         Idempotent — applying twice is a no-op.
 * - `metadata_removed`  — delete one metadata key if present. Requires:
 *                         metadataKey.
 */
/**
 * One field of one entity of a prefab, overridden at the instance. Also the
 * on-disk shape a scene stores an instance's edits as.
 *
 * @beta
 */
export interface PrefabOverride {
    prefabEntityId: PrefabEntityId;
    type:
        | 'property'
        | 'component_added'
        | 'component_replaced'
        | 'component_removed'
        | 'name'
        | 'visibility'
        | 'parent'
        | 'metadata_set'
        | 'metadata_removed';
    componentType?: string;
    propertyName?: string;
    metadataKey?: string;
    value?: unknown;
    componentData?: ComponentData;
}

export interface ProcessedEntity {
    /** Runtime entity id assigned by the flatten allocator. */
    id: number;
    /** Stable identity from the source prefab; preserved for diff/override matching. */
    prefabEntityId: PrefabEntityId;
    name: string;
    parent: number | null;
    children: number[];
    components: ComponentData[];
    visible: boolean;
    metadata?: Record<string, unknown>;
}

export interface FlattenContext {
    allocateId: () => number;
    loadPrefab: (path: string) => PrefabData | null;
    visited?: Set<string>;
    depth?: number;
    /**
     * When present, a nested instance that is virtual (see deferred.ts) is flattened to its root only and a record of what it would
     * be made from is pushed here. Absent: every instance is flattened whole.
     */
    deferred?: DeferredRecord[];
}

export interface FlattenResult {
    entities: ProcessedEntity[];
    rootId: number;
    /** Overrides whose target is no entity of the prefab — by the address they
     *  name, which a caller reports: applied nowhere, they change nothing. */
    unresolved: PrefabOverride[];
}