@needle-tools/engine/lib/engine/engine_instantiate_resolve.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import type { Object3D } from "three";
import { type GuidsMap, type UIDProvider } from "./engine_types.js";
export type ObjectCloneReference = {
    readonly original: object;
    readonly clone: object;
};
/** Maps uuid/guid → { original, clone } for Object3D and Component instances */
export type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
/**
 * Provides access to the instantiated object map (used by EventList etc.)
 */
export type InstantiateContext = Readonly<InstantiateReferenceMap>;
/** Clear the id provider cache (e.g. when reloading a context) */
export declare function clearIdProviderCache(): void;
export declare const originalComponentNameKey: unique symbol;
/**
 * Recursively generates new deterministic guids for all objects and components in a hierarchy.
 * Uses the idProviderCache so that the same source guid always produces the same output guid
 * (needed for networking: all clients must agree on the guids of instantiated objects).
 * Populates guidsMap (oldGuid → newGuid) so string references can be remapped afterwards.
 */
export declare function generateGuidsForHierarchy(obj: Object3D, idProvider: UIDProvider | null, guidsMap: GuidsMap): void;
/**
 * The unified reference resolution function.
 * Iterates all cloned components in the objectMap and remaps their properties
 * to point at cloned counterparts where appropriate.
 *
 * Handles: Component, Object3D, Array, Map, Set, Record/plain objects,
 * EventList, Vector/Color/Quaternion, and @serializable nested objects.
 */
export declare function resolveInstanceReferences(objectMap: InstantiateReferenceMap): void;
/**
 * Resolves string-based guid references in all components of a hierarchy using a GuidsMap.
 * Used by the glTF loading path where objects get new guids assigned and string references
 * (e.g. PlayableDirector track.outputs) need to be updated.
 */
export declare function resolveStringGuidsInHierarchy(root: Object3D, guidsMap: GuidsMap): void;
/**
 * Resolve a single value, returning the remapped value or undefined if no remap needed.
 * This is the core remapping logic called recursively for nested structures.
 */
export declare function resolveValue(key: string, value: unknown, objectMap: InstantiateReferenceMap): any | undefined;