@needle-tools/engine/lib/engine/engine_networking_prefabs.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 { Object3D } from "three";
/**
 * Callback type for prefab providers.
 * @param guid The guid of the prefab to resolve
 * @returns The prefab Object3D, or null if not found
 */
export declare type PrefabProviderCallback = (guid: string) => Promise<Object3D | null>;
/**
 * Prefab registry for networked instantiation.
 *
 * When a remote {@link syncInstantiate} event is received, the engine looks up the prefab
 * by its guid using this registry. Both GLB-loaded objects and runtime-created objects
 * can be registered here.
 *
 * Note: {@link syncInstantiate} auto-registers prefabs if no provider exists for their guid,
 * so manual registration is only needed for custom resolution logic.
 *
 * @example
 * ```ts
 * import { Prefabs, ObjectUtils } from "@needle-tools/engine";
 *
 * const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
 * cookie.guid = "cookie-prefab";
 * Prefabs.register("cookie-prefab", async () => cookie);
 *
 * console.log(Prefabs.list()); // ["cookie-prefab"]
 * Prefabs.unregister("cookie-prefab");
 * ```
 *
 * @category Networking
 */
export declare const Prefabs: {
    /**
     * Register a prefab provider that resolves objects by guid for networked instantiation.
     * When a remote `syncInstantiate` event is received, the engine uses this to find the prefab
     * to clone on the receiving client.
     *
     * @param key The guid to register the provider for
     * @param fn Callback that returns the prefab Object3D for the given guid
     */
    readonly register: (key: string, fn: PrefabProviderCallback) => void;
    /**
     * Unregister a previously registered prefab provider.
     * @param key The guid to unregister
     */
    readonly unregister: (key: string) => void;
    /**
     * Returns a list of all registered prefab provider keys (guids).
     * Useful for debugging to see which prefabs are available for networked instantiation.
     */
    readonly list: () => string[];
    /**
     * Check if a prefab provider is registered for the given guid.
     * @param key The guid to check
     */
    readonly has: (key: string) => boolean;
    /** @internal Resolve a prefab by guid. Used by the networking system. */
    readonly resolve: (guid: string) => Promise<Object3D | null>;
};