@relu-interactives/spatial-ecs 0.2.17 → 0.2.21

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, m as ComponentClass, n as ParentLookup, o as EcsEntityKind, O as ObjectManagementSystem } from './System-BeuJ1xt5.cjs';
-export { A as AssetInput, p as CheckboxInput, q as ColorInput, r as ComponentFactory, s as ComponentInput, t as ComponentKind, u as DropdownInput, v as DropdownOption, w as EcsComponentFactoryKind, x as EcsEntityEditorKind, y as EntityId, z as EntityInput, F as FloatInput, I as InputSystem, B as IntersectionResult, K as KeyboardKey, G as KeyboardKeys, M as MouseButton, R as RenderSystem, S as SelectionListener, H as SliderInput, J as TextInput, L as ToggleInput, N as TransformSyncSystem, Q as Vec3, U as Vector2Input, X as Vector3Input } from './System-BeuJ1xt5.cjs';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-me3iAcMF.cjs';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-me3iAcMF.cjs';
 import * as THREE from 'three';
-import { O as Object3DRef } from './Video-D4B-z74P.cjs';
-export { a2 as AnimationStateCallbacks, a3 as AnimationStateMachine, a4 as AnimationStateManager, a5 as StateMachine } from './Video-D4B-z74P.cjs';
-export { i as CoreComponents } from './index-BfoOC2CG.cjs';
+import { O as Object3DRef } from './Video-U9hAnf9y.cjs';
+export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-U9hAnf9y.cjs';
+export { i as CoreComponents } from './index-CZo5I5Gs.cjs';
 export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, ScriptBehaviourSystem, SelectionContext, VideoSystem } from './systems/index.cjs';
 export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
@@ -136,6 +136,31 @@ declare class Behaviour implements CustomEcsSystem {
      * @param world - The owning world at disposal time.
      */
     dispose?(world: World): void;
+    /**
+     * Instantiate a prefab asset into the world at runtime.
+     *
+     * `source` is typically an `AssetInput` field from this script's `data`
+     * (drag a `.prefab` from the asset browser onto the field in the editor),
+     * a URL string, or a pre-loaded `PrefabAsset`. Resolves with the new root
+     * entity id.
+     *
+     * ```ts
+     * data = { enemyPrefab: { path: "", type: "prefab" } };
+     * async onUpdate() {
+     *   if (shouldSpawn) {
+     *     const id = await this.spawnPrefab(this.data.enemyPrefab, {
+     *       position: { x: 0, y: 0, z: -5 },
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    spawnPrefab(source: SpawnPrefabSource, options?: SpawnPrefabOptions): Promise<number>;
+    /**
+     * Remove a spawned prefab instance (the root entity and all descendants).
+     * Returns the number of entities removed.
+     */
+    despawn(rootEntityId: number): number;
     /**
      * Returns the entity's world-space position as a new `THREE.Vector3`, or
      * `null` if the entity has no scene presence.
@@ -260,6 +285,32 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+type ComponentValueMaps = {
+    object3DRefValues: Map<number, unknown>;
+    nameValues: Map<number, unknown>;
+    transformValues: Map<number, unknown>;
+    modelValues: Map<number, unknown>;
+    imageValues: Map<number, unknown>;
+    spriteValues: Map<number, unknown>;
+    videoValues: Map<number, unknown>;
+    cameraValues: Map<number, unknown>;
+    environmentValues: Map<number, unknown>;
+    postprocessingValues: Map<number, unknown>;
+    audioValues: Map<number, unknown>;
+    imageTargetValues: Map<number, unknown>;
+    lightValues: Map<number, unknown>;
+    materialValues: Map<number, unknown>;
+    meshGeometryValues: Map<number, unknown>;
+    selectableValues: Map<number, unknown>;
+    physicsValues: Map<number, unknown>;
+    animationValues: Map<number, unknown>;
+    imageTargetAnchorValues: Map<number, unknown>;
+    scriptValues: Map<number, unknown>;
+    instancedMeshValues: Map<number, unknown>;
+    instanceSlotValues: Map<number, unknown>;
+    prefabNodeValues: Map<number, unknown>;
+    prefabInstanceValues: Map<number, unknown>;
+};
 type EcsWorldComponentSnapshot = {
     component: string;
     entries: Array<{
@@ -275,12 +326,40 @@ type EcsWorldStateSnapshotLike = {
 type HydrateWorldFromSnapshotResult = {
     restoredCount: number;
     selectedEntityId: number | null;
+    /** Snapshot entity id → created live entity id for every hydrated entity. */
+    idMap: Map<number, number>;
+};
+/**
+ * Optional behavior tweaks for {@link hydrateWorldFromSnapshotDetailed}.
+ * Defaults preserve the historical full-world-load behavior; prefab/subtree
+ * instantiation passes stricter options.
+ */
+type HydrateOptions = {
+    /**
+     * When false, no camera in the snapshot is promoted to the world camera.
+     * Defaults to true (full scene loads want their default camera active);
+     * prefab spawns pass false so a spawned camera never hijacks the view.
+     */
+    assignPrimaryCamera?: boolean;
+    /**
+     * "world" (default) re-applies local transforms for every entity in the
+     * world after parent links restore — correct for full scene loads.
+     * "created" limits the pass to entities created by THIS hydrate call, so
+     * mid-session spawns don't touch unrelated live entities.
+     */
+    applyTransformsScope?: "world" | "created";
 };
 declare const HYDRATABLE_ENTITY_KINDS: Set<EcsEntityKind>;
 
-declare function hydrateWorldFromSnapshotDetailed(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem): HydrateWorldFromSnapshotResult;
+declare function hydrateWorldFromSnapshotDetailed(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem, options?: HydrateOptions): HydrateWorldFromSnapshotResult;
 declare function hydrateWorldFromSnapshot(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem): number;
 
+declare function buildComponentValueMaps(snapshot: EcsWorldStateSnapshotLike): ComponentValueMaps;
+
+declare function restoreComponentState(world: World, objectManagementSystem: ObjectManagementSystem, targetEntityId: number, sourceEntityId: number, entityType: string | null, values: ComponentValueMaps): void;
+
+declare function restorePostCreateComponents(world: World, objectManagementSystem: ObjectManagementSystem, targetEntityId: number, sourceEntityId: number, entityType: string | null, values: ComponentValueMaps, idMap: Map<number, number>): void;
+
 /**
  * Override where the DRACO decoder files (draco_wasm_wrapper.js,
  * draco_decoder.wasm, draco_decoder.js) are fetched from. Embedding apps
@@ -311,4 +390,231 @@ declare function loadSharedGltf(url: string, load: () => Promise<GLTF>): Promise
  */
 declare function clearModelCache(url?: string): void;
 
-export { Behaviour, Component, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, HYDRATABLE_ENTITY_KINDS, type HydrateWorldFromSnapshotResult, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, World, WorldEntityView, clearModelCache, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath };
+/**
+ * Pure JSON-space prefab patching: apply a nested prefab's NEW definition to
+ * every top-level-relative instance region inside a HOST document snapshot,
+ * honoring the region's stored per-property overrides. This is how edits to
+ * a child prefab cascade through the `.prefab` files that nest it (no live
+ * world exists for files). Reused later by `.scene` assets.
+ *
+ * Trust model: the region's stored override list (refreshed at every host
+ * save with `+node` addition markers) IS the user state — no old base is
+ * needed. Consequently the operation is idempotent: re-applying the same
+ * definition yields `changed: false`.
+ */
+
+type ApplyPrefabToSnapshotResult = {
+    snapshot: SubtreeSnapshot;
+    changed: boolean;
+};
+/**
+ * Patch every top-level-relative nested instance of `nestedUrl` inside
+ * `hostSnapshot` with `newNestedSnapshot`. Deeper nesting (B inside C inside
+ * A) is NOT touched here — it cascades through C's own file.
+ */
+declare function applyPrefabToSnapshotInstances(hostSnapshot: SubtreeSnapshot, nestedUrl: string, newNestedSnapshot: SubtreeSnapshot): ApplyPrefabToSnapshotResult;
+
+/**
+ * Collect the given roots plus every descendant, BFS parent-first, using the
+ * `ParentId` component edges. Parent-first ordering matters: serialization
+ * renumbers ids in this order and instantiation creates entities in file
+ * order, so parents always exist before their children are linked.
+ */
+declare function collectEntitySubtree(world: World, rootIds: EntityId[]): EntityId[];
+
+/**
+ * Direct (top-level-relative) prefab urls a document depends on — the edges
+ * of the nesting graph. Deeper nesting is reached transitively through each
+ * dependency's own file, never directly.
+ */
+declare function collectDirectPrefabDependencies(snapshot: SubtreeSnapshot): string[];
+
+/**
+ * Scoped node identity for (possibly nested) prefab documents.
+ *
+ * A nodeKey identifies an entity within one prefab document even when the
+ * document contains nested instances of other prefabs (whose nodeIds repeat
+ * per instance). Formula (parent-first walk from the scope root, inherited
+ * `prefix`; the scope root's prefix is "" even if it carries PrefabInstance):
+ *
+ * - entity WITHOUT PrefabInstance:  key = prefix + nodeId, children inherit
+ *   the same prefix;
+ * - entity WITH PrefabInstance (non-scope-root): childPrefix = prefix +
+ *   instanceId + "/";  key = childPrefix + nodeId (self-inclusive — sibling
+ *   instances of the SAME prefab get distinct keys); children inherit
+ *   childPrefix.
+ *
+ * Documents with no nested instances degenerate to bare nodeIds, so v1 files
+ * and override lists keep their exact meaning.
+ */
+
+declare const NODE_KEY_SEPARATOR = "/";
+/**
+ * Reserved override "component" marking a node ADDED by the host document
+ * inside a nested instance region (`"<nodeKey>|+node|"`). File patching
+ * trusts stored overrides (the old base is unavailable), so without the
+ * marker a host-authored node inside the region would be indistinguishable
+ * from a node the child prefab removed — and get deleted.
+ */
+declare const ADDED_NODE_MARKER_COMPONENT = "+node";
+type NodeKeyMaps = {
+    idToKey: Map<number, string>;
+    keyToId: Map<string, number>;
+    /** nodeKey of the scope root (bare nodeId), or null when it has none. */
+    rootKey: string | null;
+    /** Entity ids of NESTED instance roots (non-scope-root PrefabInstance). */
+    boundaryIds: Map<number, {
+        url: string;
+        instanceId: string;
+    }>;
+};
+declare function buildNodeKeyMapsFromSnapshot(snapshot: SubtreeSnapshot, options?: {
+    scopeRootEntityId?: number;
+}): NodeKeyMaps;
+/** JSON-space subtree ids (root first, BFS) via ParentId edges. */
+declare function collectSnapshotSubtreeIds(snapshot: SubtreeSnapshot, rootEntityId: number): number[];
+type NestedRegion = {
+    rootEntityId: number;
+    url: string;
+    instanceId: string;
+    overrides: string[];
+};
+/**
+ * TOP-LEVEL-RELATIVE nested instance regions of a document: instance roots
+ * that are not the scope root and not themselves inside another region.
+ * Deeper nesting is reached by cascading through the intermediate prefab's
+ * own file, never directly.
+ */
+declare function findTopLevelNestedRegions(snapshot: SubtreeSnapshot): NestedRegion[];
+
+type InstantiateSubtreeResult = {
+    /** Live entity id of the subtree root, or null when nothing hydrated. */
+    rootId: EntityId | null;
+    /** Snapshot entity id → live entity id. */
+    idMap: Map<number, number>;
+};
+/**
+ * Hydrate a self-contained subtree snapshot (a prefab file's `snapshot`)
+ * into a LIVE world: fresh entity ids, internal references remapped, no
+ * camera promotion, transform pass scoped to the created entities.
+ */
+declare function instantiateSubtree(world: World, objectManagementSystem: ObjectManagementSystem, snapshot: SubtreeSnapshot): InstantiateSubtreeResult;
+
+/**
+ * Per-property prefab override model — pure JSON-space functions shared by
+ * the editor (diff/merge at apply time) and future `.scene` tooling.
+ *
+ * The core problem: an instance's entity ids differ from the prefab file's
+ * ids by construction, so raw values can't be compared. Both sides are first
+ * CANONICALIZED into nodeId-space: every entity-id-bearing field (kept in
+ * sync with `snapshotIdUtils.ts`) becomes `{ $node: "<nodeId>" }` when the id
+ * maps to a node inside the same document, or stays a raw id when external.
+ * Two canonical values are equal iff they describe the same state relative
+ * to their own subtree.
+ *
+ * Override encoding (stored in `PrefabInstance.overrides`):
+ *   "<nodeId>|<ComponentName>|<slash/separated/path>"
+ *   "<nodeId>|<ComponentName>|"    // empty path = whole component overridden
+ */
+
+/** Components that never participate in override diffing/merging. */
+declare const OVERRIDE_DIFF_EXCLUDED_COMPONENTS: Set<string>;
+/**
+ * Components excluded ONLY on the instance ROOT node — these are per-instance
+ * by definition (where the instance sits in the scene and what it's called).
+ */
+declare const OVERRIDE_ROOT_EXCLUDED_COMPONENTS: Set<string>;
+type NodeMaps = {
+    idToNode: Map<number, string>;
+    nodeToId: Map<string, number>;
+    /** nodeId of the subtree root (entity whose ParentId is null/absent). */
+    rootNodeId: string | null;
+};
+/** Entity ids of entities whose ParentId is null or absent. */
+declare function findSnapshotRootEntityIds(snapshot: SubtreeSnapshot): number[];
+declare function buildNodeMapsFromSnapshot(snapshot: SubtreeSnapshot): NodeMaps;
+/** Invert the columnar snapshot into entityId → (componentName → value). */
+declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, Map<string, unknown>>;
+/**
+ * Canonicalize a serialized component value into nodeId-space:
+ * - entity-id fields → `{$node}` (internal) or raw id (external)
+ * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
+ *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - Object3DRef keeps only `{visibility}` (the rest is a live object ref)
+ *
+ * Keep the id-bearing field list in sync with `snapshotIdUtils.ts`.
+ */
+declare function canonicalizeComponentValue(componentName: string, value: unknown, idToNode: Map<number, string>): unknown;
+/**
+ * Replace every `{$node}` marker (at any depth) with the mapped entity id
+ * from `nodeToId`, or null when the node no longer exists. Exact inverse of
+ * canonicalization for the id-bearing positions.
+ */
+declare function decanonicalizeComponentValue(value: unknown, nodeToId: Map<string, number>): unknown;
+declare const encodeOverride: (nodeId: string, componentName: string, path: string) => string;
+declare function parseOverride(encoded: string): {
+    nodeId: string;
+    componentName: string;
+    path: string;
+} | null;
+/** nodeId → componentName → set of overridden paths. */
+declare function groupOverridePaths(overrides: string[]): Map<string, Map<string, Set<string>>>;
+/**
+ * Collect leaf paths where two canonical values differ. Semantics:
+ * - `{$node}` refs compare atomically by nodeId
+ * - arrays of differing length are ONE atomic override (the array path);
+ *   equal lengths recurse per index
+ * - object key present on one side only marks that key's path
+ * - type mismatches mark the current path
+ * An empty-string path means the values differ at the top level.
+ */
+declare function collectDiffPaths(base: unknown, current: unknown, prefix?: string, out?: string[]): string[];
+/**
+ * Diff a live instance subtree against its prefab base (both as serialized
+ * subtree snapshots carrying PrefabNode identity) and return the encoded
+ * override list: every path where the instance deviates from the base.
+ *
+ * Identity is nodeKey-scoped ({@link buildNodeKeyMapsFromSnapshot}), so
+ * nested instance regions diff correctly; for nested-free documents the
+ * keys degenerate to bare nodeIds (v1 behavior unchanged).
+ *
+ * Policies: components missing on the instance produce no override (apply
+ * re-adds them); components/nodes only on the instance are local additions
+ * and produce no override — EXCEPT when `emitAdditionMarkers` is set
+ * (file-space callers), which records `"<key>|+node|"` for instance nodes
+ * absent from the base so pure-JSON patching never deletes host-authored
+ * nodes inside nested regions.
+ */
+declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot, options?: {
+    emitAdditionMarkers?: boolean;
+}): string[];
+/**
+ * Merge a component's NEW canonical file value with an instance's canonical
+ * value, preserving the instance side at every overridden path. An empty
+ * path ("") means the whole component is overridden → instance wins.
+ */
+declare function mergeComponentValue(newFileCanonical: unknown, instanceCanonical: unknown, overridePaths: Set<string> | undefined): unknown;
+
+type SerializeEntitySubtreeResult = {
+    snapshot: SubtreeSnapshot;
+    /**
+     * References that pointed OUTSIDE the subtree and were nulled out
+     * (ids are LIVE world ids so callers can name the offending entities).
+     * The root's own external parent link is nulled silently — it is expected.
+     */
+    warnings: ExternalRefWarning[];
+    /** Component types stripped because they are scene singletons. */
+    strippedComponents: string[];
+};
+/**
+ * Serialize `rootId` + all descendants into a self-contained snapshot:
+ * entity ids renumbered 1..N in BFS parent-first order, all internal id
+ * references remapped, external references nulled + reported, root ParentId
+ * forced to null. The result is directly consumable by
+ * `hydrateWorldFromSnapshotDetailed` / `instantiateSubtree`.
+ */
+declare function serializeEntitySubtree(world: World, rootId: EntityId, options?: {
+    maxDepth?: number;
+}): SerializeEntitySubtreeResult;
+
+export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };