@needle-tools/engine 5.0.3 → 5.1.0-alpha.1

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;
@@ -7632,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
 }
@@ -8041,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 */
@@ -8285,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.
@@ -9196,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;
@@ -9451,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>;
 }
@@ -9581,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;
@@ -11802,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` */
@@ -12844,6 +13008,12 @@ export declare class ObjectUtils {
     private static applyDefaultObjectOptions;
 }
 
+/**
+ * Remove a listener for before an XR session is requested
+ * @param fn The function to remove from the listeners
+ */
+export declare function offBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void): void;
+
 /* Excluded from this release type: OffscreenCanvasExt */
 
 /**
@@ -12948,6 +13118,21 @@ export declare function onAfterRender(cb: LifecycleMethod, opts?: LifecycleMetho
  * */
 export declare function onBeforeRender(cb: LifecycleMethod, opts?: LifecycleMethodOptions): () => void;
 
+/**
+ * Add a listener that fires before an XR session is requested.
+ * Use this to modify the session init options, e.g. to add optional features like `camera-access`.
+ * @param fn The function to call before the XR session is requested
+ * @example
+ * ```js
+ * onBeforeXRSession((args) => {
+ *   args.init.optionalFeatures ??= [];
+ *   args.init.optionalFeatures.push("camera-access");
+ * });
+ * ```
+ * @return A function to remove the listener
+ */
+export declare function onBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void): () => void;
+
 /**
  * Register a callback before the engine context is cleared.
  * This happens if e.g. `<needle-engine src>` changes
@@ -13108,6 +13293,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
@@ -13134,8 +13354,9 @@ export declare function onUpdate(cb: LifecycleMethod, opts?: LifecycleMethodOpti
  *    console.log("XR session ended", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
-export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): void;
+export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): () => void;
 
 /**
  * Add a listener for when an XR session starts
@@ -13147,8 +13368,9 @@ export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): v
  *   console.log("XR session started", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
-export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
+export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void): () => void;
 
 /**
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
@@ -13630,6 +13852,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _gainSubscription;
          private _lostSubscription;
          private _hasOwnerResponse;
+         private _pendingOwnershipResolve;
          constructor(connection: NetworkConnection, guid: string);
          private _isWaitingForOwnershipResponseCallback;
          /**
@@ -13651,21 +13874,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.
@@ -14714,7 +14939,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
           */
@@ -14724,11 +14967,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;
@@ -14932,6 +15179,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.
@@ -14960,8 +15285,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.
@@ -14988,10 +15314,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) */
@@ -15053,7 +15377,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;
@@ -15106,8 +15430,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
@@ -15823,7 +16204,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 */
 
@@ -17632,7 +18017,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;
          /**
@@ -17724,6 +18108,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare type SessionRequestedEvent = (args: {
          readonly mode: XRSessionMode;
          readonly init: XRSessionInit;
+         readonly context: Context;
      }) => void;
 
      export declare function setActive(go: Object3D, active: boolean | number): boolean;
@@ -19361,6 +19746,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 {
@@ -19410,6 +19813,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;
@@ -19526,7 +19931,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 */
@@ -19719,13 +20127,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">;
 
@@ -19808,19 +20270,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;
@@ -19828,8 +20346,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;
@@ -19856,7 +20372,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,
@@ -19865,8 +20381,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 {
@@ -19878,7 +20393,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 {
@@ -20082,10 +20598,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;
@@ -20344,6 +20862,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;
@@ -20479,6 +21013,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 {
@@ -20987,7 +21527,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          protected get primaryAxis(): Axis;
      }
 
-     declare enum VerticalWrapMode {
+     export declare enum VerticalWrapMode {
          Truncate = 0,
          Overflow = 1
      }
@@ -21446,6 +21986,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 */
@@ -21478,6 +22059,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;
@@ -21487,6 +22071,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();
@@ -21512,11 +22099,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);
@@ -21524,6 +22114,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
@@ -21532,21 +22123,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;
          /**
@@ -21554,17 +22145,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;
@@ -22806,6 +23397,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          session: NeedleXRSession;
      };
 
+     export declare type XRSessionRequestEventArgs = {
+         readonly mode: XRSessionMode;
+         readonly init: XRSessionInit;
+         readonly context: Context;
+     };
+
      export declare class XRState {
          static Global: XRState;
          Mask: XRStateFlag;