@needle-tools/engine 5.0.2 → 5.1.0-canary.525aa82

package/dist/needle-engine.d.ts

@@ -22,6 +22,7 @@ import { DocumentedOptions } from '../../../node_modules/three-mesh-ui/build/typ
 import { Effect } from 'postprocessing';
 import { EffectComposer } from 'postprocessing';
 import { EffectComposer as EffectComposer_2 } from '../../node_modules/@types/three/examples/jsm/postprocessing/EffectComposer.js';
+import { EffectComposer as EffectComposer_3 } from '../../../node_modules/@types/three/examples/jsm/postprocessing/EffectComposer.js';
 import { EmitterShape } from 'three.quarks';
 import { Euler } from 'three';
 import { EventDispatcher } from 'three';
@@ -90,6 +91,7 @@ import { Sprite as Sprite_2 } from 'three';
 import { SpriteMaterial } from 'three';
 import { Texture } from 'three';
 import * as ThreeMeshUI from 'three-mesh-ui';
+import { ToneMapping } from 'three';
 import { TransformControls } from '../../node_modules/@types/three/examples/jsm/controls/TransformControls.js';
 import { Vector2 } from 'three';
 import { Vector2Like } from 'three';
@@ -644,29 +646,36 @@ declare class AnimationTriggers {
 /**
  * Utility class for working with animations.
  */
-export declare class AnimationUtils {
+export declare namespace AnimationUtils {
     /**
      * Tests if the root object of an AnimationAction can be animated. Objects where matrixAutoUpdate or matrixWorldAutoUpdate is set to false may not animate correctly.
      * @param action The AnimationAction to test
      * @param allowLog Whether to allow logging warnings. Default is false, which only allows logging in development environments.
      * @returns True if the root object can be animated, false otherwise
      */
-    static testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean;
+    export function testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean;
     /**
      * Tries to get the animation actions from an animation mixer.
      * @param mixer The animation mixer to get the actions from
      * @returns The actions or null if the mixer is invalid
      */
-    static tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null;
-    static tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip>;
+    export function tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null;
+    export function tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip>;
+    /** Internal method - This marks an object as being animated. Make sure to always call isAnimated=false if you stop animating the object
+     * @param obj The object to mark
+     * @param isAnimated Whether the object is animated or not
+     */
+    export function setObjectAnimated(obj: Object3D, animatedBy: object, isAnimated: boolean): void;
+    /** Get is the object is currently animated. Currently used by the Animator to check if a timeline animationtrack is actively animating an object */
+    export function getObjectAnimated(obj: Object3D): boolean;
     /**
      * Assigns animations from a GLTF file to the objects in the scene.
      * This method will look for objects in the scene that have animations and assign them to the correct objects.
      * @param file The GLTF file to assign the animations from
      */
-    static autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null;
-    static emptyClip(): AnimationClip;
-    static createScaleClip(options?: ScaleClipOptions): AnimationClip;
+    export function autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null;
+    export function emptyClip(): AnimationClip;
+    export function createScaleClip(options?: ScaleClipOptions): AnimationClip;
 }
 
 /**
@@ -909,8 +918,9 @@ export declare enum AnimatorConditionMode {
  * and parameters that affect those transitions. It is used by the {@link Animator}
  * component to control animation behavior on 3D models.
  *
- * Use the static method {@link AnimatorController.createFromClips} to create
- * an animator controller from a set of animation clips.
+ * Use {@link AnimatorController.build} to fluently create a controller with parameters,
+ * states, transitions, and conditions. For simple sequential playback,
+ * use {@link AnimatorController.createFromClips}.
  *
  * @category Animation and Sequencing
  * @group Utilities
@@ -925,6 +935,27 @@ export declare class AnimatorController {
      * @returns A new AnimatorController instance
      */
     static createFromClips(clips: AnimationClip[], options?: CreateAnimatorControllerOptions): AnimatorController;
+    /**
+     * Creates a new {@link AnimatorControllerBuilder} for fluently constructing a controller with
+     * parameters, states, transitions, and conditions.
+     *
+     * @param name - Optional name for the controller
+     * @returns A new builder instance
+     *
+     * @example
+     * ```ts
+     * const ctrl = AnimatorController.build("MyController")
+     *     .floatParameter("Speed")
+     *     .state("Idle", { clip: idleClip, loop: true })
+     *     .state("Walk", { clip: walkClip, loop: true })
+     *     .transition("Idle", "Walk", { duration: 0.25 })
+     *         .condition("Speed", "greater", 0.1)
+     *     .transition("Walk", "Idle", { duration: 0.25 })
+     *         .condition("Speed", "less", 0.1)
+     *     .build();
+     * ```
+     */
+    static build(name?: string): AnimatorControllerBuilder;
     /**
      * Plays an animation state by name or hash.
      *
@@ -1116,6 +1147,84 @@ export declare class AnimatorController {
     private rootMotionHandler?;
 }
 
+/**
+ * A fluent builder for creating {@link AnimatorController} instances from code.
+ *
+ * Use {@link AnimatorController.build} to create a new builder.
+ *
+ * @example
+ * ```ts
+ * const controller = AnimatorController.build("CharacterController")
+ *     .floatParameter("Speed", 0)
+ *     .triggerParameter("Jump")
+ *     .state("Idle", { clip: idleClip, loop: true })
+ *     .state("Walk", { clip: walkClip, loop: true })
+ *     .state("Jump", { clip: jumpClip })
+ *     .transition("Idle", "Walk", { duration: 0.25 })
+ *         .condition("Speed", "greater", 0.1)
+ *     .transition("Walk", "Idle", { duration: 0.25 })
+ *         .condition("Speed", "less", 0.1)
+ *     .transition("*", "Jump", { duration: 0.1 })
+ *         .condition("Jump", "if")
+ *     .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
+ *     .build();
+ * ```
+ *
+ * @category Animation and Sequencing
+ * @group Utilities
+ */
+export declare class AnimatorControllerBuilder {
+    private _name;
+    private _parameters;
+    private _states;
+    private _anyStateTransitions;
+    private _defaultStateName;
+    private _lastTransition;
+    constructor(name?: string);
+    /** Adds a float parameter */
+    floatParameter(name: string, defaultValue?: number): this;
+    /** Adds an integer parameter */
+    intParameter(name: string, defaultValue?: number): this;
+    /** Adds a boolean parameter */
+    boolParameter(name: string, defaultValue?: boolean): this;
+    /** Adds a trigger parameter */
+    triggerParameter(name: string): this;
+    /**
+     * Adds a state to the controller. The first state added becomes the default state.
+     * @param name - Unique name for the state
+     * @param options - State configuration including clip, loop, speed
+     */
+    state(name: string, options: StateOptions): this;
+    /**
+     * Adds a transition between two states.
+     * Use `"*"` as the source to create a transition from any state.
+     * Chain `.condition()` calls after this to add conditions.
+     * @param from - Source state name, or `"*"` for any-state transition
+     * @param to - Destination state name
+     * @param options - Transition configuration
+     */
+    transition(from: string, to: string, options?: TransitionOptions): this;
+    /**
+     * Adds a condition to the most recently added transition.
+     * Multiple conditions on the same transition are AND-ed together.
+     * @param parameter - Name of the parameter to evaluate
+     * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
+     * @param threshold - Comparison threshold for numeric conditions (default: 0)
+     */
+    condition(parameter: string, mode: ConditionMode, threshold?: number): this;
+    /**
+     * Sets which state is the default/entry state.
+     * If not called, the first added state is used.
+     * @param name - Name of the state
+     */
+    defaultState(name: string): this;
+    /**
+     * Builds and returns the {@link AnimatorController}.
+     * Resolves all state name references to indices.
+     */
+    build(): AnimatorController;
+}
+
 export declare type AnimatorControllerModel = {
     name: string;
     guid: string;
@@ -3997,6 +4106,9 @@ export declare type Condition = {
     threshold: number;
 };
 
+/** String condition modes for the builder, mapped to {@link AnimatorConditionMode} */
+export declare type ConditionMode = "if" | "ifNot" | "greater" | "less" | "equals" | "notEqual";
+
 /** Events regarding the websocket connection (e.g. when the connection opens) */
 export declare enum ConnectionEvents {
     ConnectionInfo = "connection-start-info"
@@ -4306,9 +4418,11 @@ export declare class Context implements IContext {
      */
     renderer: WebGLRenderer;
     /**
-     * The effect composer can be used to render postprocessing effects. If assigned then it will automatically render the scene every frame.
+     * The effect composer used for rendering postprocessing effects.
+     * @deprecated Use `context.postprocessing.composer` instead.
      */
-    composer: EffectComposer | EffectComposer_2 | null;
+    get composer(): EffectComposer | EffectComposer_2 | null;
+    set composer(value: EffectComposer | EffectComposer_2 | null);
     /* Excluded from this release type: scripts */
     /* Excluded from this release type: scripts_pausedChanged */
     /* Excluded from this release type: scripts_earlyUpdate */
@@ -4359,6 +4473,8 @@ export declare class Context implements IContext {
     input: Input;
     /** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
     physics: Physics;
+    /** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
+    postprocessing: PostProcessing;
     /** access networking methods (use it to send or listen to messages or join a networking backend) */
     connection: NetworkConnection;
     /**  @deprecated AssetDatabase is deprecated */
@@ -6432,7 +6548,7 @@ declare enum FogMode {
     ExponentialSquared = 3
 }
 
-declare enum FontStyle {
+export declare enum FontStyle {
     Normal = 0,
     Bold = 1,
     Italic = 2,
@@ -7280,7 +7396,8 @@ export declare class Gradient {
 export declare class Graphic extends BaseUIComponent implements IGraphic, IRectTransformChangedReceiver {
     get isGraphic(): boolean;
     get color(): RGBAColor;
-    set color(col: RGBAColor);
+    set color(col: RGBAColor | Color);
+    private _color;
     private _alphaFactor;
     setAlphaFactor(factor: number): void;
     get alphaFactor(): number;
@@ -7289,7 +7406,6 @@ export declare class Graphic extends BaseUIComponent implements IGraphic, IRectT
     private get m_Color();
     raycastTarget: boolean;
     protected uiObject: ThreeMeshUI.Block | null;
-    private _color;
     private _rect;
     private _stateManager;
     protected get rectTransform(): RectTransform;
@@ -7503,6 +7619,7 @@ export declare class GroundProjectedEnv extends Component {
     updateProjection(): void;
     private _blurrynessShader;
     private _lastBlurriness;
+    private updateProjectionMaterial;
     private updateBlurriness;
 }
 
@@ -7631,7 +7748,7 @@ declare abstract class HorizontalOrVerticalLayoutGroup extends LayoutGroup {
     protected onCalculateLayout(rect: RectTransform): void;
 }
 
-declare enum HorizontalWrapMode {
+export declare enum HorizontalWrapMode {
     Wrap = 0,
     Overflow = 1
 }
@@ -8040,7 +8157,11 @@ export declare interface IInputEventArgs {
     stopImmediatePropagation?(): void;
 }
 
+/**
+ * Options for instantiating a GameObject, used in {@link instantiate} and {@link syncInstantiate}
+ */
 export declare type IInstantiateOptions = {
+    /** The ID provider for generating unique IDs / guids */
     idProvider?: UIDProvider;
     parent?: string | Object3D;
     /** position in local space. Set `keepWorldPosition` to true if this is world space */
@@ -8284,6 +8405,10 @@ export declare class InheritVelocityModule {
     applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
 }
 
+/** Register the Rapier physics backend. Called from {@link initEngine}
+ * to ensure it runs regardless of tree-shaking. */
+export declare function initPhysics(): void;
+
 /**
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
  * Access via `this.context.input` from any component.
@@ -9195,6 +9320,32 @@ export declare interface IPointerUpHandler {
     onPointerUp?(args: PointerEventData): any;
 }
 
+/**
+ * Minimal interface for a postprocessing effect as seen by the core stack.
+ * Implemented by `PostProcessingEffect` in engine-components.
+ */
+export declare interface IPostProcessingEffect {
+    readonly active: boolean;
+    readonly enabled: boolean;
+    /** When true, this effect is a tonemapping effect. The core stack uses this to detect tonemapping-only scenarios. */
+    readonly isToneMapping?: boolean;
+}
+
+/**
+ * Interface for the pipeline builder that manages the EffectComposer.
+ * Implemented by `PostProcessingHandler` in engine-components.
+ */
+export declare interface IPostProcessingHandler {
+    readonly composer: EffectComposer | EffectComposer_3 | null;
+    readonly hasSmaaEffect: boolean;
+    multisampling: number;
+    adaptivePixelRatio: boolean;
+    apply(effects: IPostProcessingEffect[]): Promise<void>;
+    unapply(dispose?: boolean): void;
+    updateAdaptivePixelRatio(): void;
+    dispose(): void;
+}
+
 declare type IPostProcessingManager = IComponent & {
     get isPostProcessingManager(): boolean;
     get dirty(): boolean;
@@ -9450,6 +9601,19 @@ export declare interface ITimelineAnimationOverride {
     onTimelinePosition?(director: PlayableDirector, target: Object3D, time: number, position: Vector3): any;
 }
 
+/**
+ * Extended interface for tonemapping effects.
+ * When ONLY tonemapping effects are in the stack, the core applies tonemapping
+ * directly to the renderer instead of creating a full postprocessing pipeline.
+ */
+export declare interface ITonemappingEffect extends IPostProcessingEffect {
+    readonly isToneMapping: true;
+    /** The three.js ToneMapping enum value to apply to the renderer */
+    readonly threeToneMapping: ToneMapping;
+    /** The exposure value to apply to the renderer */
+    readonly toneMappingExposure: number;
+}
+
 declare interface ITypeInformation {
     type?: ConstructorConcrete<any>;
 }
@@ -9580,7 +9744,7 @@ declare abstract class LayoutGroup extends Component implements ILayoutGroup {
     get isDirty(): boolean;
     get isLayoutGroup(): boolean;
     updateLayout(): void;
-    childAlignment: TextAnchor;
+    childAlignment: TextAnchor_2;
     reverseArrangement: boolean;
     spacing: number;
     padding: Padding;
@@ -11801,6 +11965,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
      * @returns true if the browser supports the given XRSessionMode
      */
     static isSessionSupported(mode: XRSessionMode): Promise<boolean>;
+    private static _sessionSupportedCache;
     private static _currentSessionRequest?;
     private static _activeSession;
     /** Register to listen to XRSession start events. Unsubscribe with `offXRSessionStart` */
@@ -13107,6 +13272,41 @@ export declare type OnRenderCallback = (renderer: WebGLRenderer, scene: Scene, c
  * */
 export declare function onStart(cb: LifecycleMethod, opts?: LifecycleMethodOptions): () => void;
 
+/**
+ * Register a callback that fires when a remote `syncDestroy` event is received.
+ * The callback receives the guid and the resolved Object3D (or null if not found in the scene).
+ * The callback fires **before** the object is destroyed, so you can still access its state.
+ * @param callback Called with the guid and the Object3D about to be destroyed
+ * @returns An unsubscribe function
+ * @category Networking
+ * @example
+ * ```ts
+ * const unsub = onSyncDestroy((guid, obj) => {
+ *   console.log("Remote object destroyed:", guid, obj?.name);
+ * });
+ * // later: unsub();
+ * ```
+ */
+export declare function onSyncDestroy(callback: SyncDestroyCallback): () => void;
+
+/**
+ * Register a callback that fires when a remote `syncInstantiate` object is created on this client.
+ * Use this to get references to objects spawned by other users.
+ * @param callback Called with the instantiated Object3D, the network model data, and the Needle Engine context in which the instantiate event was received
+ * @returns An unsubscribe function
+ * @category Networking
+ * @example
+ * ```ts
+ * const unsub = onSyncInstantiate((instance, model, context) => {
+ *   console.log("Remote object created:", instance.name, model.originalGuid, context);
+ * });
+ * // later: unsub();
+ * ```
+ * @see {@link syncInstantiate} - Instantiate objects across the network
+ * @see {@link syncDestroy} - Destroy objects across the network
+ */
+export declare function onSyncInstantiate(callback: SyncInstantiateCallback): () => void;
+
 /** Register a callback in the engine update event
  * This is called every frame
  * @param cb The callback to be called
@@ -13370,6 +13570,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
       get targetLerpDuration(): number;
       set targetLerpDuration(v: number);
       private _lookTargetLerpDuration;
+      /**
+       * When set, the camera's look at target will be clamped within the bounds of the specified Object3D. The bounds are defined by the world position and world scale of the assigned Object3D.
+       * @default null
+       */
       targetBounds: Object3D | null;
       /**
        * Rotate the camera left (or right) by the specified angle in radians.
@@ -13625,6 +13829,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _gainSubscription;
          private _lostSubscription;
          private _hasOwnerResponse;
+         private _pendingOwnershipResolve;
          constructor(connection: NetworkConnection, guid: string);
          private _isWaitingForOwnershipResponseCallback;
          /**
@@ -13646,21 +13851,23 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @throws Rejects with "Timeout" if ownership is not gained within ~1 second
           * @example
           * ```ts
-          * try {
-          *   await ownership.requestOwnershipAsync();
+          * const owned = await ownership.requestOwnership();
+          * if (owned) {
           *   // Ownership granted, safe to modify object
-          * } catch(e) {
-          *   console.warn("Could not gain ownership:", e);
           * }
           * ```
           */
-         requestOwnershipAsync(): Promise<OwnershipModel>;
          /**
           * Requests ownership of this object from the networking server.
-          * Ownership may not be granted immediately - check `hasOwnership` property or use `requestOwnershipAsync()`.
-          * @returns this OwnershipModel instance for method chaining
+          * Returns a Promise that resolves with `true` when ownership is granted, or `false` on timeout/failure.
+          * If ownership is already held, resolves immediately with `true`.
+          * @returns Promise that resolves with `true` if ownership was gained, `false` otherwise
+          */
+         requestOwnership(): Promise<boolean>;
+         /**
+          * @deprecated Use `requestOwnership()` instead for a more reliable way to gain ownership
           */
-         requestOwnership(): OwnershipModel;
+         requestOwnershipAsync(): Promise<OwnershipModel>;
          /**
           * Releases ownership of this object, allowing others to take control.
           * Call this when you're done modifying an object to allow other users to interact with it.
@@ -14709,7 +14916,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * scene.add(res.gameObject);
           * ```
           */
-         static setupFrom(url: string, init?: Omit<ComponentInit<PlayerSync>, "asset">): Promise<PlayerSyncWithAsset>;
+         /**
+          * This API is experimental and may change or be removed in the future.
+          * Creates a PlayerSync instance at runtime from a given URL or Object3D and sets it up for networking.
+          * @param urlOrObject Path to the asset that should be instantiated for each player, or a pre-created Object3D to use as the player prefab
+          * @param init Optional initialization parameters for the PlayerSync component
+          * @returns Promise resolving to a PlayerSync instance with a guaranteed asset property
+          * @example
+          * ```typescript
+          * // From a GLB URL:
+          * const res = await PlayerSync.setupFrom("/assets/demo.glb");
+          *
+          * // From a runtime-created Object3D:
+          * const avatar = ObjectUtils.createPrimitive("Sphere");
+          * const res = await PlayerSync.setupFrom(avatar);
+          * ```
+          */
+         static setupFrom(urlOrObject: string | Object3D, init?: Omit<ComponentInit<PlayerSync>, "asset"> & {
+             guid?: string;
+         }): Promise<PlayerSyncWithAsset>;
          /**
           * When enabled, PlayerSync will automatically load and instantiate the assigned asset when joining a networked room
           */
@@ -14719,11 +14944,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          asset?: AssetReference;
          /**
-          * Event invoked when a player instance is spawned with the spawned {@link Object3D} as parameter
+          * Event invoked when ANY player instance is spawned — both local and remote.
+          * The event argument is a {@link PlayerSpawnedEventArgs} with the player Object3D and whether it's the local player.
+          * For backward compatibility, the first argument is also the Object3D directly.
           * @serializable
           */
-         onPlayerSpawned?: EventList<Object3D>;
+         onPlayerSpawned: EventList<Object3D>;
          private _localInstance?;
+         private _unsubSyncInstantiate?;
+         constructor();
          awake(): void;
          onEnable(): void;
          onDisable(): void;
@@ -14927,6 +15156,84 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      export declare function postprocessFBXMaterials(obj: Mesh, material: Material | Material[], index?: number, array?: Material[]): boolean;
 
+     /**
+      * Core postprocessing stack accessible via `context.postprocessing`.
+      * Manages the effect pipeline independently of any specific component.
+      *
+      * Volumes and individual PostProcessingEffect components add/remove effects
+      * to this stack. The stack builds the EffectComposer pipeline when dirty.
+      *
+      * @example Add an effect directly
+      * ```ts
+      * const bloom = new BloomEffect({ intensity: 3 });
+      * this.context.postprocessing.addEffect(bloom);
+      * ```
+      *
+      * @example Remove an effect
+      * ```ts
+      * this.context.postprocessing.removeEffect(bloom);
+      * ```
+      */
+     export declare class PostProcessing {
+         private readonly _context;
+         private _handler;
+         private readonly _effects;
+         private _isDirty;
+         /** Currently active postprocessing effects in the stack */
+         get effects(): readonly IPostProcessingEffect[];
+         get dirty(): boolean;
+         set dirty(value: boolean);
+         /** The internal PostProcessingHandler that manages the EffectComposer pipeline */
+         get handler(): IPostProcessingHandler | null;
+         /**
+          * The effect composer used to render postprocessing effects.
+          * This is set internally by the PostProcessingHandler when effects are applied.
+          */
+         get composer(): EffectComposer | EffectComposer_3 | null;
+         set composer(value: EffectComposer | EffectComposer_3 | null);
+         private _composer;
+         /**
+          * Set multisampling to "auto" to automatically adjust the multisampling level based on performance.
+          * Set to a number to manually set the multisampling level.
+          * @default "auto"
+          */
+         multisampling: "auto" | number;
+         /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
+          * and restored when performance recovers.
+          * @default true
+          */
+         adaptiveResolution: boolean;
+         constructor(context: Context);
+         /**
+          * Add a post processing effect to the stack.
+          * The effect stack will be rebuilt on the next update.
+          */
+         addEffect(effect: IPostProcessingEffect): void;
+         /**
+          * Remove a post processing effect from the stack.
+          * The effect stack will be rebuilt on the next update.
+          */
+         removeEffect(effect: IPostProcessingEffect): void;
+         /** Mark the stack as dirty so the effects are rebuilt on the next update */
+         markDirty(): void;
+         private _enabledTime;
+         private _multisampleAutoChangeTime;
+         private _multisampleAutoDecreaseTime;
+         /* Excluded from this release type: update */
+         private _lastApplyTime?;
+         private _rapidApplyCount;
+         /** When true, tonemapping is applied directly to the renderer (no full pipeline) */
+         private _tonemappingOnlyActive;
+         private _previousToneMapping?;
+         private _previousToneMappingExposure?;
+         private apply;
+         /** Restore renderer tonemapping to previous values when leaving tonemapping-only mode */
+         private restoreTonemapping;
+         /** Lazily creates the PostProcessingHandler to avoid loading the postprocessing library until actually needed */
+         private ensureHandler;
+         /* Excluded from this release type: dispose */
+     }
+
      /**
       * PostProcessingEffect is a base class for post processing effects that can be applied to the scene.
       * To create a custom post processing effect, extend this class and override the `onCreateEffect` method and call `registerCustomEffectType` to make it available in the editor.
@@ -14955,8 +15262,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * @category Effects
       * @group Components
+      * @see {@link PostProcessing} for core Needle Engine postprocessing control, also accessible via `context.postprocessing`
       */
-     export declare abstract class PostProcessingEffect extends Component implements IEffectProvider, IEditorModification {
+     export declare abstract class PostProcessingEffect extends Component implements IPostProcessingEffect, IEffectProvider, IEditorModification {
          get isPostProcessingEffect(): boolean;
          /**
           * The order of this effect. The higher the order the later the effect will be applied in the post processing stack.
@@ -14983,10 +15291,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @deprecated
           */
          active: boolean;
-         private _manager;
          onEnable(): void;
          onDisable(): void;
-         protected onEffectEnabled(manager?: IPostProcessingManager): void;
          /** override to initialize bindings on parameters */
          init(): void;
          /** previously created effect (if any) */
@@ -15048,7 +15354,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * [PostProcessingHandler](https://engine.needle.tools/docs/api/PostProcessingHandler) Is responsible for applying post processing effects to the scene. It is internally used by the {@link Volume} component
       */
-     export declare class PostProcessingHandler {
+     export declare class PostProcessingHandler implements IPostProcessingHandler {
          private _composer;
          private _lastVolumeComponents?;
          private readonly _effects;
@@ -15101,8 +15407,65 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _onCreateEffectsDebug;
      }
 
+     /**
+      * 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;
+         /* Excluded from this release type: resolve */
+     };
+
      export declare type Prefix = (...args: any[]) => any;
 
      /** Experimental attribute
@@ -15818,7 +16181,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export declare function registerLoader<T extends INeedleGltfLoader>(loader: ConstructorConcrete<T>): void;
 
-     export declare function registerPrefabProvider(key: string, fn: PrefabProviderCallback): void;
+     /**
+      * Register a prefab provider. Forwards to {@link Prefabs.register}.
+      * @category Networking
+      */
+     export declare function registerPrefabProvider(key: string, fn: (guid: string) => Promise<Object3D | null>): void;
 
      /* Excluded from this release type: registerPrototypeExtensions */
 
@@ -17627,7 +17994,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _needsUpdate;
          private _id;
          /* Excluded from this release type: onEnable */
-         /* Excluded from this release type: onDisable */
          /* Excluded from this release type: update */
          private updateDirection;
          /**
@@ -19356,6 +19722,24 @@ export declare class OrbitControls extends Component implements ICameraControlle
          instance?: StateMachineBehaviour;
      };
 
+     /**
+      * Configuration for an animation state in the builder
+      */
+     export declare type StateOptions = {
+         /** The animation clip for this state */
+         clip: AnimationClip;
+         /** Whether the animation should loop (default: false) */
+         loop?: boolean;
+         /** Base speed multiplier (default: 1) */
+         speed?: number;
+         /** Name of a float parameter to multiply with speed */
+         speedParameter?: string;
+         /** Normalized cycle offset 0-1 (default: 0) */
+         cycleOffset?: number;
+         /** Name of a float parameter to use as cycle offset */
+         cycleOffsetParameter?: string;
+     };
+
      declare type StickName = "xr-standard-thumbstick" | "xr-standard-touchpad";
 
      export declare class StreamEndedEvent {
@@ -19405,6 +19789,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      export declare function syncDestroy(obj: IGameObject | IComponent, con: INetworkConnection, recursive?: boolean, opts?: SyncDestroyOptions): void;
 
+     declare type SyncDestroyCallback = (guid: string, object: Object3D) => void;
+
      declare type SyncDestroyOptions = {
          /** When true the state will be saved in the networking backend */
          saveInRoom?: boolean;
@@ -19521,7 +19907,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
          get roomPrefix(): string;
          private _roomPrefix;
          /* Excluded from this release type: awake */
+         private _hasConnectedBefore;
          /* Excluded from this release type: onEnable */
+         /* Excluded from this release type: start */
+         private _connectToRoom;
          /* Excluded from this release type: onDisable */
          /* Excluded from this release type: onDestroy */
          /** Will generate a random room name, set it as an URL parameter and attempt to join the room */
@@ -19714,13 +20103,67 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }) => void;
 
      /**
-      * Instantiate an object across the network. See also {@link syncDestroy}.
+      * Instantiate an object across the network. The object is cloned locally and a network message
+      * is sent so all connected clients create the same clone. Late joiners receive the message
+      * via room state replay (unless `deleteOnDisconnect` is set or `save` is false).
+      *
+      * ## How it works internally
+      * 1. The prefab is cloned locally using a seeded {@link InstantiateIdProvider}
+      * 2. The seed ensures all clients generate **identical deterministic guids** for the clone
+      *    and all its children — no need to send individual guids over the network
+      * 3. A {@link NewInstanceModel} message is sent containing the prefab's `originalGuid`,
+      *    the clone's `guid`, the `seed`, and transform data
+      * 4. On receiving clients, the prefab is resolved via {@link registerPrefabProvider} or
+      *    by searching the scene for an object with matching guid, then cloned with the same seed
+      *
+      * ## Runtime-created prefabs (no GLB)
+      * If the object has a `guid` but no prefab provider is registered for it, `syncInstantiate`
+      * will **auto-register** the object as a prefab provider. This means for code-only prefabs
+      * you just need to set a `guid` — no manual `registerPrefabProvider` call needed, as long as
+      * all clients run the same setup code that creates the same prefab with the same guid.
+      *
+      * @param object The object to instantiate. Must have a `guid` property (set one for runtime objects).
+      * @param opts Options for the instantiation, including the network context to send the instantiate event to
+      * @param hostData Optional data about a file to download when this object is instantiated (e.g. when instantiated via file drop)
+      * @param save When false, the state of this instance will not be saved in the networking backend. Default is true.
+      * @returns The instantiated object, or null if instantiation failed (e.g. missing guid or network context)
+      * @see {@link syncDestroy} - Destroy objects across the network
+      * @see {@link onSyncInstantiate} - Register a callback to get references to remotely instantiated objects
+      * @see {@link registerPrefabProvider} - Manually register a prefab provider (auto-registered by syncInstantiate)
+      * @see {@link unregisterPrefabProvider} - Remove a registered prefab provider
       * @category Networking
+      *
+      * @example Basic usage with a runtime-created prefab
+      * ```ts
+      * const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
+      * cookie.guid = "cookie-prefab";
+      * // No need to call registerPrefabProvider — syncInstantiate auto-registers it
+      * syncInstantiate(cookie, { parent: ctx.scene, deleteOnDisconnect: false });
+      * ```
+      *
+      * @example With deterministic seed (advanced)
+      * ```ts
+      * const idProvider = new InstantiateIdProvider("my-seed");
+      * const instance = syncInstantiate(prefab, { context, idProvider });
+      * ```
+      * The seed generates deterministic guids via UUID v5, so all clients produce identical
+      * identifiers for the clone and its children without sending them over the network.
       */
      export declare function syncInstantiate(object: IGameObject | Object3D, opts: SyncInstantiateOptions, hostData?: HostData, save?: boolean): IGameObject | null;
 
+     /**
+      * Callback type for {@link onSyncInstantiate}
+      * @param instance The instantiated object
+      * @param model The network model data sent with the instantiate event
+      * @param context The network context in which the instantiate event was received
+      * @category Networking
+      */
+     declare type SyncInstantiateCallback = (instance: IGameObject, model: NewInstanceModel, context: IContext) => void;
+
      /**
       * Instantiation options for {@link syncInstantiate}
+      * @category Networking
+      * @see {@link syncInstantiate} - Instantiate objects across the network
       */
      export declare type SyncInstantiateOptions = IInstantiateOptions & Pick<IModel, "deleteOnDisconnect">;
 
@@ -19803,19 +20246,75 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @see {@link FontStyle} for bold/italic styles
       */
      declare class Text_2 extends Graphic implements IHasAlphaFactor, ICanvasEventReceiver {
-         alignment: TextAnchor_2;
-         verticalOverflow: VerticalWrapMode;
-         horizontalOverflow: HorizontalWrapMode;
-         lineSpacing: number;
-         supportRichText: boolean;
-         font?: string;
-         fontStyle: FontStyle;
+         /**
+          * The alignment of the text within its container. This determines how the text is anchored and positioned relative to its RectTransform. For example, `UpperLeft` will anchor the text to the upper left corner of the container, while `MiddleCenter` will center the text both horizontally and vertically. Changing this property will update the underlying three-mesh-ui options and mark the UI as dirty to trigger a re-render.
+          */
+         set alignment(val: TextAnchor);
+         get alignment(): TextAnchor;
+         private _alignment;
+         /**
+          * Determines how text that exceeds the vertical bounds of the container is handled. If set to `Truncate`, any text that goes beyond the vertical limits of the container will be cut off and not visible. If set to `Overflow`, the text will continue to render outside the container bounds, which may result in it being partially or fully visible depending on the layout and parent containers.
+          * @default VerticalWrapMode.Truncate
+          */
+         set verticalOverflow(val: VerticalWrapMode);
+         get verticalOverflow(): VerticalWrapMode;
+         private _verticalOverflow;
+         /**
+          * Determines how text that exceeds the horizontal bounds of the container is handled. If set to `Wrap`, the text will automatically wrap to the next line when it reaches the edge of the container. If set to `Overflow`, the text will continue on a single line and may overflow outside the container bounds.
+          * @default HorizontalWrapMode.Wrap
+          */
+         set horizontalOverflow(val: HorizontalWrapMode);
+         get horizontalOverflow(): HorizontalWrapMode;
+         private _horizontalOverflow;
+         /**
+          * The line spacing multiplier for the text. A value of 1 means normal spacing, 1.5 means 50% more spacing, and 0.5 means 50% less spacing.
+          * @default 1
+          */
+         set lineSpacing(val: number);
+         get lineSpacing(): number;
+         private _lineSpacing;
+         /**
+          * The style of the font, which can be normal, bold, italic, or bold and italic.
+          *
+          * This is used to determine the correct font variant to use based on the provided `font` property. For example, if you set `font` to "Arial" and `fontStyle` to `FontStyle.Bold`, it will look for a font variant named "Arial-Bold" (or "arial-bold") in the font library. If such a variant exists, it will be used to render the text with the specified style.
+          *
+          * @default FontStyle.Normal
+          */
+         set fontStyle(val: FontStyle);
+         get fontStyle(): FontStyle;
+         private _fontStyle;
+         /**
+          * The font to use for the text, specified as a URL to a font file.
+          *
+          * The font file must be in MSDF format. You can generate MSDF fonts using tools like [msdf-bmfont-xml](https://github.com/Chlumsky/msdf-bmfont-xml) or by using Needle Engine for Unity where the Needle Engine integration automatically generates MSDF fonts for used font assets.
+          *
+          * @default "https://cdn.needle.tools/static/fonts/msdf/arial/arial"
+          */
+         set font(val: string | null);
+         get font(): string | null;
+         private _font;
+         /**
+          * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
+          * @default false
+          */
+         set supportRichText(val: boolean);
+         get supportRichText(): boolean;
+         private _supportRichText;
+         /**
+          * Set the alpha factor for the text, which multiplies with the color's alpha to determine overall transparency.
+          */
          setAlphaFactor(factor: number): void;
+         /**
+          * The text content to display. Supports basic rich text tags like `<b>`, `<i>`, and `<color=hex>` if `supportRichText` is enabled.
+          * @default ""
+          */
          get text(): string;
          set text(val: string);
+         private _text;
          private set_text;
          get fontSize(): number;
          set fontSize(val: number);
+         private _fontSize;
          private sRGBTextColor;
          protected onColorChanged(): void;
          onParentRectTransformChanged(): void;
@@ -19823,8 +20322,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private updateOverflow;
          protected onCreate(_opts: any): void;
          onAfterAddedToScene(): void;
-         private _text;
-         private _fontSize;
          private _textMeshUi;
          private getTextOpts;
          onEnable(): void;
@@ -19851,7 +20348,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
      export { Text_2 as Text }
 
-     declare enum TextAnchor {
+     export declare enum TextAnchor {
          UpperLeft = 0,
          UpperCenter = 1,
          UpperRight = 2,
@@ -19860,8 +20357,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          MiddleRight = 5,
          LowerLeft = 6,
          LowerCenter = 7,
-         LowerRight = 8,
-         Custom = 9
+         LowerRight = 8
      }
 
      declare enum TextAnchor_2 {
@@ -19873,7 +20369,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          MiddleRight = 5,
          LowerLeft = 6,
          LowerCenter = 7,
-         LowerRight = 8
+         LowerRight = 8,
+         Custom = 9
      }
 
      export declare class TextBuilder {
@@ -20077,10 +20574,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /** Set the tonemapping mode to e.g. "agx" */
          setMode(mode: NEToneMappingModeNames): this;
          get isToneMapping(): boolean;
-         onEffectEnabled(): void;
+         /** The three.js ToneMapping enum value resolved from the current mode */
+         get threeToneMapping(): ToneMapping;
+         /** The exposure value to apply */
+         get toneMappingExposure(): number;
          private _tonemappingEffect;
          onCreateEffect(): EffectProviderResult | undefined;
-         onBeforeRender(): void;
      }
 
      export declare function toSourceId(src: string | null): SourceIdentifier | undefined;
@@ -20339,6 +20838,22 @@ export declare class OrbitControls extends Component implements ICameraControlle
          Animation = 3
      }
 
+     /**
+      * Configuration for a transition in the builder
+      */
+     export declare type TransitionOptions = {
+         /** Duration of the crossfade in seconds (default: 0) */
+         duration?: number;
+         /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
+         exitTime?: number;
+         /** Whether the transition waits for exitTime before transitioning (default: false) */
+         hasExitTime?: boolean;
+         /** Normalized offset into the destination state's animation (default: 0) */
+         offset?: number;
+         /** Whether duration is in seconds (true) or normalized (false) (default: false) */
+         hasFixedDuration?: boolean;
+     };
+
      export declare class TriggerBuilder {
          private static __sceneStartTrigger?;
          static sceneStartTrigger(): TriggerModel;
@@ -20474,6 +20989,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /* Excluded from this release type: unregisterHotReloadType */
 
+     /**
+      * Unregister a prefab provider. Forwards to {@link Prefabs.unregister}.
+      * @category Networking
+      */
+     export declare function unregisterPrefabProvider(key: string): void;
+
      export declare function unwatchWrite(vec: Vector_2, cb: Function): void;
 
      export declare class UriSerializer extends TypeSerializer {
@@ -20982,7 +21503,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          protected get primaryAxis(): Axis;
      }
 
-     declare enum VerticalWrapMode {
+     export declare enum VerticalWrapMode {
          Truncate = 0,
          Overflow = 1
      }
@@ -21441,6 +21962,47 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * When enabled debug messages will be printed to the console. This is useful for debugging audio issues. You can also append ?debugvoip to the URL to enable this.
           */
          debug: boolean;
+         private _volume;
+         /**
+          * Volume for incoming audio streams (0 = silent, 1 = full volume).
+          * Changes apply immediately to all active incoming streams.
+          */
+         get volume(): number;
+         set volume(val: number);
+         /**
+          * Get the incoming audio element for a specific user.
+          * Use this to route audio through the Web Audio API for spatial audio, effects, or analysis.
+          * @param userId The connection ID of the remote user
+          * @returns The HTMLAudioElement for this user's stream, or undefined if not connected
+          * @example
+          * ```ts
+          * const audioEl = voip.getAudioElement(userId);
+          * if (audioEl) {
+          *   const audioCtx = new AudioContext();
+          *   const source = audioCtx.createMediaElementSource(audioEl);
+          *   const panner = audioCtx.createPanner();
+          *   source.connect(panner).connect(audioCtx.destination);
+          * }
+          * ```
+          */
+         getAudioElement(userId: string): HTMLAudioElement | undefined;
+         /**
+          * Get all active incoming audio streams as a Map of userId → HTMLAudioElement.
+          * Useful for iterating over all connected voice users.
+          */
+         get incomingStreams(): ReadonlyMap<string, HTMLAudioElement>;
+         /**
+          * Threshold for speaking detection (0–255). When a user's audio amplitude exceeds this,
+          * they are considered "speaking". Default is 30.
+          */
+         speakingThreshold: number;
+         /**
+          * Event fired when a user's speaking state changes.
+          * Passes `{ userId: string, isSpeaking: boolean, volume: number }`.
+          */
+         onSpeakingChanged: EventList;
+         private _speakingStates;
+         private _analysers;
          private _net?;
          private _menubutton?;
          /* Excluded from this release type: awake */
@@ -21473,6 +22035,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private onJoinedRoom;
          private onLeftRoom;
          private _incomingStreams;
+         /* Excluded from this release type: update */
+         private setupAnalyser;
+         private cleanupAnalyser;
          private onReceiveStream;
          private onStreamEnded;
          private onEnabledChanged;
@@ -21482,6 +22047,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /** [Volume](https://engine.needle.tools/docs/api/Volume) The Volume/PostprocessingManager component is responsible for managing post processing effects.
       * Add this component to any object in your scene to enable post processing effects.
       *
+      * Effects added to this Volume (via profile or code) are pushed to `context.postprocessing` when the Volume is enabled,
+      * and removed when it is disabled.
+      *
       * @example Add bloom
       * ```ts
       * const volume = new Volume();
@@ -21507,11 +22075,14 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @summary Manage Post-Processing Effects
       * @category Rendering
       * @category Effects
+      * @see {@link VolumeProfile} for profile-based effect management
+      * @see {@link PostProcessingEffect} for creating custom effects
+      * @see {@link PostProcessing} for core Needle Engine postprocessing control, also accessible via `context.postprocessing`
       * @group Components
       */
      declare class Volume extends Component implements IEditorModification, IPostProcessingManager {
          get isPostProcessingManager(): boolean;
-         /** Currently active postprocessing effects */
+         /** Currently active postprocessing effects managed by this Volume */
          get effects(): PostProcessingEffect[];
          get dirty(): boolean;
          set dirty(value: boolean);
@@ -21519,6 +22090,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /**
           * Set multisampling to "auto" to automatically adjust the multisampling level based on performance.
           * Set to a number to manually set the multisampling level.
+          * Pushed to `context.postprocessing.multisampling` when this Volume is active.
           * @default "auto"
           * @min 0
           * @max renderer.capabilities.maxSamples
@@ -21527,21 +22099,21 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
           * and restored when performance recovers. This helps maintain smooth frame rates
           * on devices where full retina resolution is too expensive for postprocessing.
+          * Pushed to `context.postprocessing.adaptiveResolution` when this Volume is active.
           * Disable this if you need a fixed resolution and prefer consistent quality over frame rate.
           * @default true
           */
          adaptiveResolution: boolean;
          /**
-          * Add a post processing effect to the stack and schedules the effect stack to be re-created.
+          * Add a post processing effect to this Volume and push it to the core postprocessing stack.
           */
          addEffect<T extends PostProcessingEffect | Effect>(effect: T & {
              order?: number;
          }): T;
          /**
-          * Remove a post processing effect from the stack and schedules the effect stack to be re-created.
+          * Remove a post processing effect from this Volume and the core postprocessing stack.
           */
          removeEffect<T extends PostProcessingEffect | Effect>(effect: T): T;
-         private _postprocessing?;
          private readonly _activeEffects;
          private readonly _effects;
          /**
@@ -21549,17 +22121,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          markDirty(): void;
          /* Excluded from this release type: awake */
-         private _componentEnabledTime;
-         private _multisampleAutoChangeTime;
-         private _multisampleAutoDecreaseTime;
+         private _isDirty;
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
          /* Excluded from this release type: onBeforeRender */
          /* Excluded from this release type: onDestroy */
-         private _lastApplyTime?;
-         private _rapidApplyCount;
-         private _isDirty;
-         private apply;
+         /** Collect active effects from profile + code and push them to context.postprocessing */
+         private pushEffectsToCore;
+         /** Remove all effects this Volume contributed from the core stack */
+         private removeEffectsFromCore;
+         /** Push multisampling and adaptiveResolution config to the core stack */
+         private syncConfigToCore;
          private _applyPostQueue;
          /** called from needle editor sync package if its active */
          onEditorModification(modification: EditorModification): void | boolean | undefined;