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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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[];
}