@needle-tools/engine 4.12.5 → 4.13.0-next.1eca7a7

package/dist/needle-engine.d.ts

@@ -48,6 +48,7 @@ import { Layers } from 'three';
 import { LightProbe } from 'three';
 import { Line2 } from 'three/examples/jsm/lines/Line2.js';
 import { Loader } from 'three';
+import { LoadingManager } from 'three';
 import { LOD_Results } from '@needle-tools/gltf-progressive';
 import { LODsManager as LODsManager_2 } from '@needle-tools/gltf-progressive';
 import { Material } from 'three';
@@ -61,6 +62,7 @@ import { n8ao } from 'n8ao';
 import { N8AOPostPass } from 'n8ao';
 import { NEEDLE_progressive } from '@needle-tools/gltf-progressive';
 import { NEEDLE_progressive_plugin } from '@needle-tools/gltf-progressive';
+import { needleToolsMaterialx } from '@needle-tools/materialx';
 import { NormalBufferAttributes } from 'three';
 import { Object3D } from 'three';
 import { Object3DEventMap } from 'three';
@@ -221,12 +223,32 @@ export declare class Addressables {
 declare type Alignment = "horizontal" | "vertical" | "any";
 
 /**
- * Aligns this GameObject between two other GameObjects, scaling it to fit the distance.
- * You can use this to create dynamic beams or connectors between objects.
+ * AlignmentConstraint positions and scales this GameObject to span between two target objects.
+ * The object is rotated to face `to` and scaled along Z to match the distance.
  *
- * @summary Aligns and scales the object between two target GameObjects
+ * **Use cases:**
+ * - Dynamic beams or laser effects between objects
+ * - Stretchy connectors or ropes
+ * - Visual links between UI elements
+ * - Debug lines between transforms
+ *
+ * **How it works:**
+ * - Position: Centered between `from` and `to` (or at `from` if not centered)
+ * - Rotation: Looks at `to` from `from`
+ * - Scale: Z-axis scales to match distance, X/Y use `width`
+ *
+ * @example Create a beam between two objects
+ * ```ts
+ * const beam = beamMesh.addComponent(AlignmentConstraint);
+ * // Set targets via serialized properties in editor
+ * // or via code if properties are exposed
+ * ```
+ *
+ * @summary Aligns and scales object between two targets
  * @category Constraints
  * @group Components
+ * @see {@link LookAtConstraint} for rotation-only constraints
+ * @see {@link SmoothFollow} for following with smoothing
  **/
 export declare class AlignmentConstraint extends Component {
     private from;
@@ -250,10 +272,46 @@ declare type Anchoring = "plane" | "image" | "face" | "none";
 
 /**
  * Animation component to play animations on a GameObject.
+ * For simpler animation needs compared to {@link Animator}, this component directly
+ * plays AnimationClips without state machine logic.
+ *
+ * **Key features:**
+ * - Play animations by index, name, or clip reference
+ * - Cross-fade between animations with `fadeDuration`
+ * - Loop or play once with optional clamping
+ * - Random start time and speed variation
+ * - Promise-based completion handling
+ *
+ *
+ * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)
+ *
+ * @example Play animation by name
+ * ```ts
+ * const anim = this.gameObject.getComponent(Animation);
+ * await anim?.play("Walk", { loop: true, fadeDuration: 0.3 });
+ * ```
+ *
+ * @example Play with options
+ * ```ts
+ * anim?.play(0, {
+ *   loop: false,
+ *   clampWhenFinished: true,
+ *   speed: 2
+ * });
+ * ```
  *
  * @summary Plays animations from AnimationClips
  * @category Animation and Sequencing
  * @group Components
+ * @see {@link Animator} for state machine-based animation
+ * @see {@link PlayOptions} for all playback options
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
+ * @link https://engine.needle.tools/samples/imunogard/
+ *
+ * @link https://engine.needle.tools/docs/blender/animation.html
+ *
+ * ![](https://cloud.needle.tools/-/media/vAYv-kU-eMpICqQZHJktCA.gif)
+ *
  */
 declare class Animation_2 extends Component implements IAnimationComponent {
     get isAnimationComponent(): boolean;
@@ -538,13 +596,46 @@ export declare class AnimationUtils {
 }
 
 /**
- * The Animator component plays and manages animations on a GameObject.
- * It works with an {@link AnimatorController} to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
+ * Animator plays and manages state-machine based animations on a GameObject.
+ * Uses an {@link AnimatorController} for state transitions, blending, and parameters.
+ *
+ * **State machine animations:**
+ * Define animation states and transitions in Unity's Animator window or in [Blender's Animator Controller editor](https://engine.needle.tools/docs/blender/animation.html)
+ * Control transitions via parameters (bool, int, float, trigger).
+ *
+ * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)
+ *
+ * **Creating at runtime:**
+ * Use `AnimatorController.createFromClips()` to create controllers from code.
+ *
+ * **Parameters:**
+ * - `setTrigger(name)` - Trigger a one-shot transition
+ * - `setBool(name, value)` - Set boolean parameter
+ * - `setFloat(name, value)` - Set float parameter
+ * - `setInteger(name, value)` - Set integer parameter
+ *
+ * @example Trigger animation state
+ * ```ts
+ * const animator = myCharacter.getComponent(Animator);
+ * animator.setTrigger("Jump");
+ * animator.setFloat("Speed", 5);
+ * animator.setBool("IsRunning", true);
+ * ```
+ *
+ * @example Listen to animation events
+ * ```ts
+ * animator.onLoop(evt => console.log("Animation looped"));
+ * animator.onFinished(evt => console.log("Animation finished"));
+ * ```
  *
  * @summary Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
+ * @see {@link AnimatorController} for state machine configuration
+ * @see {@link Animation} for simple clip playback
+ * @see {@link PlayableDirector} for timeline-based animation
+ *
+ * @link https://engine.needle.tools/docs/blender/animation.html
  */
 export declare class Animator extends Component implements IAnimationComponent {
     /**
@@ -1261,23 +1352,45 @@ declare enum AudioRolloffMode {
 }
 
 /**
- * Plays audio clips in the scene, with support for spatial positioning.
+ * Plays audio clips in the scene with support for spatial (3D) positioning.
+ *
+ * **Browser autoplay policies:**
+ * Web browsers require user interaction before playing audio. Use
+ * `AudioSource.userInteractionRegistered` to check if playback is allowed,
+ * or `registerWaitForAllowAudio()` to queue playback until interaction occurs.
  *
- * The AudioSource component can play audio files or media streams with
- * options for spatial blending, volume control, looping, and more.
+ * **Spatial audio:**
+ * Set `spatialBlend` to 1 for full 3D positioning, or 0 for 2D (non-spatial).
+ * Requires an {@link AudioListener} in the scene (typically on the camera).
  *
- * When a page loses visibility (tab becomes inactive), audio will automatically
- * pause unless {@link playInBackground} is set to true. On mobile devices, audio always
- * pauses regardless of this setting. When the page becomes visible again,
- * previously playing audio will resume.
+ * **Visibility handling:**
+ * Audio automatically pauses when the tab is hidden unless `playInBackground = true`.
+ * On mobile, audio always pauses in background regardless of this setting.
+ *
+ * @example Play audio on button click
+ * ```ts
+ * onClick() {
+ *   const audio = this.getComponent(AudioSource);
+ *   audio.play();
+ * }
+ * ```
  *
- * AudioSource also responds to application mute state changes. When the application
- * is muted, the volume is set to 0. When unmuted, the volume
- * returns to its previous value.
+ * @example Wait for user interaction
+ * ```ts
+ * AudioSource.registerWaitForAllowAudio(() => {
+ *   this.getComponent(AudioSource)?.play();
+ * });
+ * ```
  *
  * @summary Plays audio clips from files or media streams
  * @category Multimedia
  * @group Components
+ * @see {@link AudioListener} for the audio receiver component
+ * @see {@link AudioRolloffMode} for distance attenuation options
+ * @see {@link Voip} for voice communication
+ * @see {@link PlayableDirector} for timeline-based audio
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=audio
+ * @link https://spatial-audio-zubckswmztj.needle.run/
  */
 export declare class AudioSource extends Component {
     /**
@@ -1573,27 +1686,62 @@ export declare class AvatarLoader {
 }
 
 /**
- * This is used to mark an object being controlled / owned by a player
- * This system might be refactored and moved to a more centralized place in a future version
+ * Marks a GameObject as being controlled or owned by a player in networked XR sessions.
+ * This is used internally by the networking system to identify player-controlled objects.
+ *
+ * **Note:** This is an internal marker class. For most use cases, use the {@link Avatar} component instead.
+ *
+ * @summary Internal marker for player-controlled objects in networked sessions
+ * @category XR
+ * @category Networking
+ * @group Components
+ * @see {@link Avatar} for avatar setup and configuration
  */
 export declare class AvatarMarker extends Component {
+    /**
+     * Get an avatar marker by index from the global list of avatar markers.
+     * @param index The index in the instances array
+     * @returns The AvatarMarker at the specified index, or null if index is out of bounds
+     */
     static getAvatar(index: number): AvatarMarker | null;
+    /** Global list of all active AvatarMarker instances */
     static instances: AvatarMarker[];
+    /**
+     * Subscribe to avatar marker creation events.
+     * @param cb Callback function called when a new avatar marker is created
+     * @returns The callback function (for removal)
+     */
     static onAvatarMarkerCreated(cb: (args: AvatarMarkerEventArgs) => void): Function;
+    /**
+     * Subscribe to avatar marker destruction events.
+     * @param cb Callback function called when an avatar marker is destroyed
+     * @returns The callback function (for removal)
+     */
     static onAvatarMarkerDestroyed(cb: (args: AvatarMarkerEventArgs) => void): Function;
     private static _onNewAvatarMarkerAdded;
     private static _onAvatarMarkerDestroyed;
+    /** The network connection ID of the player who owns this avatar */
     connectionId: string;
+    /** Reference to the avatar GameObject with optional XR flags */
     avatar?: Object3D & {
         flags?: XRFlag[];
     };
-    awake(): void;
-    onDestroy(): void;
+    /* Excluded from this release type: awake */
+    /* Excluded from this release type: onDestroy */
+    /**
+     * Check if this avatar marker represents the local player.
+     * @returns True if this avatar belongs to the local player, false otherwise
+     */
     isLocalAvatar(): boolean;
 }
 
+/**
+ * Event arguments for avatar marker creation and destruction events
+ */
 declare type AvatarMarkerEventArgs = {
+    /** The AvatarMarker component instance */
     avatarMarker: AvatarMarker;
+    /** The GameObject that contains the avatar marker */
     gameObject: Object3D;
 };
 
@@ -1635,12 +1783,31 @@ export declare enum Axes {
 }
 
 /**
- * Component that visualizes the axes of an object in the scene.
- * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
+ * AxesHelper visualizes the local coordinate axes of an object.
+ * Displays colored lines for X (red), Y (green), and Z (blue) axes.
  *
- * @summary Visualizes object axes in the scene
+ * **Use cases:**
+ * - Debugging object orientation and rotation
+ * - Visualizing pivot points
+ * - Understanding coordinate systems
+ *
+ * **Properties:**
+ * - `length` - Length of axis lines in world units
+ * - `depthTest` - Whether axes are occluded by scene objects
+ * - `isGizmo` - Only show when `?gizmos` URL parameter is set
+ *
+ * @example Add axes visualization
+ * ```ts
+ * const axes = myObject.addComponent(AxesHelper);
+ * axes.length = 2;
+ * axes.depthTest = false; // Always visible on top
+ * ```
+ *
+ * @summary Visualizes object axes (X=red, Y=green, Z=blue)
  * @category Helpers
  * @group Components
+ * @see {@link GridHelper} for grid visualization
+ * @see {@link Gizmos} for debug drawing utilities
  */
 export declare class AxesHelper extends Component {
     /**
@@ -1714,12 +1881,35 @@ export declare class BaseUIComponent extends Component {
 }
 
 /**
- * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.
- * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
+ * BasicIKConstraint provides simple two-bone inverse kinematics.
+ * Positions this GameObject as a "joint" between `from` and `to` targets,
+ * using a `hint` object to determine the bend direction.
  *
- * @summary Simple Inverse Kinematics Constraint
- * @category Animation
+ * **Use cases:**
+ * - Simple arm/leg IK (elbow/knee positioning)
+ * - Mechanical linkages
+ * - Procedural animation joints
+ *
+ * **How it works:**
+ * - Calculates joint position based on `desiredDistance` (bone length)
+ * - Uses `hint` to determine which way the joint bends
+ * - Automatically handles stretching when targets are too far apart
+ *
+ * @example Setup basic limb IK
+ * ```ts
+ * // Attach to the elbow/knee joint object
+ * const ik = elbowJoint.addComponent(BasicIKConstraint);
+ * // Configure via serialized properties in editor:
+ * // - from: shoulder/hip
+ * // - to: wrist/ankle
+ * // - hint: control point for bend direction
+ * ```
+ *
+ * @summary Two-bone inverse kinematics constraint
+ * @category Animation and Sequencing
  * @group Components
+ * @see {@link LookAtConstraint} for aim constraints
+ * @see {@link AlignmentConstraint} for simpler alignment
  */
 export declare class BasicIKConstraint extends Component {
     private from;
@@ -1885,15 +2075,31 @@ export declare class BloomEffect extends PostProcessingEffect {
 }
 
 /**
- * BoxCollider represents a box-shaped collision volume.
- * Ideal for rectangular objects or objects that need a simple cuboid collision boundary.
+ * BoxCollider represents a box-shaped (cuboid) collision volume.
+ * Most common collider type, efficient for walls, floors, crates, and rectangular objects.
+ *
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * @example Create a floor collider
+ * ```ts
+ * const box = floor.addComponent(BoxCollider);
+ * box.size = new Vector3(10, 0.1, 10);
+ * box.center = new Vector3(0, -0.05, 0);
+ * ```
+ *
+ * @example Auto-fit to mesh geometry
+ * ```ts
+ * const collider = BoxCollider.add(myMesh, { rigidbody: true });
+ * // Collider size is automatically set from mesh bounds
+ * ```
  *
  * - Example: https://samples.needle.tools/physics-basic
- * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation
  *
+ * @summary Box-shaped physics collider
  * @category Physics
  * @group Components
+ * @see {@link Collider} for base collider functionality
+ * @see {@link SphereCollider} for sphere shapes
  */
 export declare class BoxCollider extends Collider implements IBoxCollider {
     /**
@@ -2002,12 +2208,38 @@ export declare const BUILD_TIME: string;
 export declare const builtinComponentKeyName = "builtin_components";
 
 /**
- * Button is a UI component that can be clicked by the user to perform an action.
- * It supports different visual states such as normal, highlighted, pressed, and disabled.
- * You can customize the button's appearance using colors or animations for each state.
+ * Button is a UI component that can be clicked to trigger actions.
+ * Supports visual states (normal, highlighted, pressed, disabled) with
+ * color tints or animation transitions.
+ *
+ * **Visual transitions:**
+ * - `ColorTint` - Tint the button image with state colors
+ * - `Animation` - Trigger animator states for each button state
+ * - `SpriteSwap` - Swap sprites for each state (not fully supported)
+ *
+ * **Requirements:**
+ * - Typically paired with an {@link Image} component for visuals or any 3D object
+ *
+ * @example Listen to button clicks
+ * ```ts
+ * const button = myButton.getComponent(Button);
+ * button.onClick.addEventListener(() => {
+ *   console.log("Button clicked!");
+ * });
+ * ```
+ *
+ * @example Programmatically click a button
+ * ```ts
+ * button.click(); // Triggers onClick event
+ * ```
+ *
  * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
+ * @see {@link EventList} for onClick callback handling
+ * @see {@link Image} for button visuals
+ * @see {@link GraphicRaycaster} for UI interaction
+ * @see {@link Transition} for visual state options
  */
 export declare class Button extends Component implements IPointerEventHandler {
     /**
@@ -2159,6 +2391,9 @@ declare class CallHandle extends EventDispatcher<any> {
     constructor(userId: string, call: MediaConnection, direction: CallDirection, stream?: MediaStream | null);
 }
 
+/**
+ * CallInfo represents a single callback method that can be invoked by the {@link EventList}.
+ */
 export declare class CallInfo {
     /**
      * When the CallInfo is enabled it will be invoked when the EventList is invoked
@@ -2182,11 +2417,41 @@ export declare class CallInfo {
 /**
  * Camera component that handles rendering from a specific viewpoint in the scene.
  * Supports both perspective and orthographic cameras with various rendering options.
- * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
+ * Internally uses three.js {@link PerspectiveCamera} or {@link OrthographicCamera}.
+ *
+ * ![](https://cloud.needle.tools/-/media/UU96_SJNXdVjaAvPNW3kZA.webp)
+ *
+ * **Background clearing:**
+ * Control how the camera clears the background using `clearFlags`:
+ * - `Skybox` - Use scene skybox/environment
+ * - `SolidColor` - Clear with `backgroundColor`
+ * - `None` - Don't clear (for layered rendering)
+ *
+ * **Render targets:**
+ * Set `targetTexture` to a {@link RenderTexture} to render to a texture
+ * instead of the screen (useful for mirrors, portals, minimaps).
+ *
+ * [![](https://cloud.needle.tools/-/media/W4tYZuJVVJFVp7NTaHPOnA.gif)](https://engine.needle.tools/samples/movie-set)
+ *
+ * @example Configure camera settings
+ * ```ts
+ * const cam = this.context.mainCameraComponent;
+ * cam.fieldOfView = 60;
+ * cam.nearClipPlane = 0.1;
+ * cam.farClipPlane = 1000;
+ * cam.clearFlags = ClearFlags.SolidColor;
+ * cam.backgroundColor = new RGBAColor(0.1, 0.1, 0.2, 1);
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/multiple-cameras
  *
  * @summary Rendering scenes from a specific viewpoint
  * @category Camera and Controls
  * @group Components
+ * @see {@link OrbitControls} for camera interaction
+ * @see {@link RenderTexture} for off-screen rendering
+ * @see {@link ClearFlags} for background clearing options
+ * @link https://engine.needle.tools/samples/movie-set/
  */
 export declare class Camera extends Component implements ICamera {
     /**
@@ -2399,12 +2664,37 @@ export declare class CameraTargetReachedEvent extends CustomEvent<{
 
 /**
  * Canvas is the root component for all UI elements in a scene.
- * It defines the area where UI elements are rendered and manages their layout and rendering settings.
- * Canvases can be set to render in world space or screen space (overlay or camera).
- * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
+ * Defines the rendering area and manages layout for child UI elements.
+ *
+ * **Render modes:**
+ * - `WorldSpace` - UI exists in 3D space, can be viewed from any angle
+ * - `ScreenSpaceOverlay` - UI rendered on top of everything (HUD)
+ * - `ScreenSpaceCamera` - UI rendered at a distance from a specific camera
+ *
+ * **Usage:**
+ * All UI components ({@link Button}, {@link Text}, {@link Image}) must be
+ * children of a Canvas to render correctly. Multiple canvases can exist
+ * in a scene with different settings.
+ *
+ * **Rendering options:**
+ * - `renderOnTop` - Always render above other objects
+ * - `depthWrite` - Write to depth buffer (affects occlusion)
+ * - `doubleSided` - Render both sides of UI elements
+ *
+ * @example Create a world-space UI panel
+ * ```ts
+ * const canvas = panel.getComponent(Canvas);
+ * canvas.renderMode = RenderMode.WorldSpace;
+ * canvas.doubleSided = true;
+ * ```
+ *
  * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
+ * @see {@link RenderMode} for rendering options
+ * @see {@link RectTransform} for UI layout
+ * @see {@link Button} for clickable UI elements
+ * @see {@link Text} for UI text rendering
  */
 export declare class Canvas extends UIRootComponent implements ICanvas {
     get isCanvas(): boolean;
@@ -2493,6 +2783,8 @@ export declare class CanvasGroup extends Component implements ICanvasGroup {
  * CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).
  * Ideal for character controllers and objects that need a rounded collision shape.
  *
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
  * - Example: https://samples.needle.tools/physics-basic
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation
@@ -2587,42 +2879,106 @@ export declare class ChangeTransformOnClick extends Component implements IPointe
 /**
  * CharacterController adds a capsule collider and rigidbody to the object, constrains rotation, and provides movement and grounded state.
  * It is designed for typical character movement in 3D environments.
+ *
+ * The controller automatically:
+ * - Creates a {@link CapsuleCollider} if one doesn't exist
+ * - Creates a {@link Rigidbody} if one doesn't exist
+ * - Locks rotation on all axes to prevent tipping over
+ * - Tracks ground contact for jump detection
+ *
+ * @example Basic character movement
+ * ```ts
+ * export class MyCharacter extends Behaviour {
+ *   @serializable(CharacterController)
+ *   controller?: CharacterController;
+ *
+ *   update() {
+ *     const input = this.context.input;
+ *     const move = new Vector3();
+ *     if (input.isKeyPressed("KeyW")) move.z = 0.1;
+ *     if (input.isKeyPressed("KeyS")) move.z = -0.1;
+ *     this.controller?.move(move);
+ *   }
+ * }
+ * ```
+ *
  * @summary Character Movement Controller
  * @category Character
  * @group Components
+ * @see {@link CharacterControllerInput} for ready-to-use input handling
+ * @see {@link Rigidbody} for physics configuration
+ * @see {@link CapsuleCollider} for collision shape
  */
 export declare class CharacterController extends Component {
+    /** Center offset of the capsule collider in local space */
     center: Vector3;
+    /** Radius of the capsule collider */
     radius: number;
+    /** Height of the capsule collider */
     height: number;
     private _rigidbody;
     get rigidbody(): Rigidbody;
     private _activeGroundCollisions;
     awake(): void;
     onEnable(): void;
+    /**
+     * Moves the character by adding the given vector to its position.
+     * Movement is applied directly without physics simulation.
+     * @param vec The movement vector to apply
+     */
     move(vec: Vector3): void;
     onCollisionEnter(col: Collision): void;
     onCollisionExit(col: Collision): void;
+    /** Returns true if the character is currently touching the ground */
     get isGrounded(): boolean;
     private _contactVelocity;
+    /**
+     * Returns the combined velocity of all objects the character is standing on.
+     * Useful for moving platforms - add this to your movement for proper platform riding.
+     */
     get contactVelocity(): Vector3;
 }
 
 /**
- * CharacterControllerInput handles user input to control a CharacterController.
+ * CharacterControllerInput handles user input to control a {@link CharacterController}.
  * It supports movement, looking around, jumping, and double jumping.
- * You can customize movement speed, rotation speed, and jump forces.
- * It also integrates with an Animator component for character animations.
+ *
+ * Default controls:
+ * - **W/S**: Move forward/backward
+ * - **A/D**: Rotate left/right
+ * - **Space**: Jump (supports double jump)
+ *
+ * The component automatically sets animator parameters:
+ * - `running` (bool): True when moving
+ * - `jumping` (bool): True when starting a jump
+ * - `doubleJump` (bool): True during double jump
+ * - `falling` (bool): True when falling from height
+ *
+ * @example Custom input handling
+ * ```ts
+ * const input = this.gameObject.getComponent(CharacterControllerInput);
+ * input?.move(new Vector2(0, 1)); // Move forward
+ * input?.jump(); // Trigger jump
+ * ```
+ *
  * @summary User Input for Character Controller
  * @category Character
  * @group Components
+ * @see {@link CharacterController} for the movement controller
+ * @see {@link Animator} for animation integration
  */
 export declare class CharacterControllerInput extends Component {
+    /** The CharacterController to drive with input */
     controller?: CharacterController;
+    /** Movement speed multiplier */
     movementSpeed: number;
+    /** Rotation speed multiplier */
     rotationSpeed: number;
+    /** Impulse force applied when jumping from ground */
     jumpForce: number;
+    /** Impulse force applied for the second jump (set to 0 to disable double jump) */
     doubleJumpForce: number;
+    /** Optional Animator for character animations */
     animator?: Animator;
     lookForward: boolean;
     awake(): void;
@@ -2765,17 +3121,43 @@ export declare type ClipModel = {
 };
 
 /**
- * Collider is the base class for all colliders. A collider is a physical shape that is used to detect collisions with other objects in the scene.
- * Colliders are used in combination with a {@link Rigidbody} to create physical interactions between objects.
- * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.
+ * Collider is the base class for all physics collision shapes.
+ * Colliders define the physical boundary of objects for collision detection.
+ *
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * **Usage with Rigidbody:**
+ * - Add a collider to define collision shape
+ * - Add a {@link Rigidbody} to the same or parent object for physics simulation
+ * - Without Rigidbody, collider acts as static geometry
+ *
+ * **Trigger mode:**
+ * Set `isTrigger = true` for detection without physical collision.
+ * Triggers fire `onTriggerEnter`, `onTriggerStay`, `onTriggerExit` events.
+ *
+ * **Collision filtering:**
+ * Use `membership` and `filter` arrays to control which objects collide.
+ *
+ * @example Add a box collider to an object
+ * ```ts
+ * const collider = myObject.addComponent(BoxCollider);
+ * collider.size = new Vector3(1, 2, 1);
+ * collider.center = new Vector3(0, 1, 0);
+ * ```
  *
  * - Example: https://samples.needle.tools/physics-basic
  * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation
  *
- * @summary Physics collider
+ * @summary Physics collider base class
  * @category Physics
  * @group Components
+ * @see {@link BoxCollider} for box-shaped colliders
+ * @see {@link SphereCollider} for sphere-shaped colliders
+ * @see {@link CapsuleCollider} for capsule-shaped colliders
+ * @see {@link MeshCollider} for mesh-based colliders
+ * @see {@link Rigidbody} for physics simulation
+ * @link https://engine.needle.tools/samples/?room=needle272&overlay=samples&tag=physics
+ * @link https://engine.needle.tools/samples-uploads/basic-physics/?showcolliders
  */
 export declare abstract class Collider extends Component implements ICollider {
     /* Excluded from this release type: isCollider */
@@ -3431,18 +3813,37 @@ export declare class ContactPoint {
 }
 
 /**
- * ContactShadows is a component that allows to display contact shadows in the scene. It has options for darkness, opacity and blur of the shadows.
+ * ContactShadows renders proximity-based soft shadows on flat surfaces.
+ * Ideal for products or objects that need visual grounding without real-time shadows.
  *
- * - Example: https://samples.needle.tools/contact-shadows
+ * ![](https://cloud.needle.tools/-/media/87bPTNXHcsbV-An-oSEvHQ.gif)
  *
- * ## Usage
- * You can use {@link ContactShadows.auto} to automatically create a ContactShadows instance for the scene or you can add the component to an object in the scene. Note that the scale of the object will be used to define the size of the shadow area.
+ * **Setup options:**
+ * 1. `ContactShadows.auto(context)` - Auto-create and fit to scene
+ * 2. Add component manually to control position and scale
+ * 3. HTML attribute: `<needle-engine contactshadows="0.7">`
  *
- * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
+ * **Properties:**
+ * - `opacity` / `darkness` - Shadow intensity
+ * - `blur` - Softness of shadow edges
+ * - Object scale defines shadow area size
+ *
+ * **Debug:** Use `?debugcontactshadows` URL parameter.
+ *
+ *
+ * @example Auto-create contact shadows
+ * ```ts
+ * const shadows = ContactShadows.auto(this.context);
+ * shadows.opacity = 0.5;
+ * shadows.darkness = 0.8;
+ * ```
  *
  * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
+ * @see {@link Light} for real-time shadow casting
+ * @see {@link Renderer} for material/rendering control
+ * @link https://engine.needle.tools/samples/contact-shadows for a demo of contact shadows
  */
 export declare class ContactShadows extends Component {
     private static readonly _instances;
@@ -3512,6 +3913,7 @@ export declare class ContactShadows extends Component {
     private plane?;
     private occluderMesh?;
     private blurPlane?;
+    private planeMaterial?;
     private depthMaterial?;
     private horizontalBlurMaterial?;
     private verticalBlurMaterial?;
@@ -4235,20 +4637,61 @@ export declare function delay(milliseconds: number): Promise<void>;
  */
 export declare function delayForFrames(frameCount: number, context?: Context): Promise<void>;
 
-/** Objects with this component can be destroyed by the {@link DeleteBox} component.
+/**
+ * Marks a GameObject as deletable by {@link DeleteBox} zones.
+ * Objects with this component will be destroyed (and synced across network)
+ * when they enter a DeleteBox area.
+ *
+ * **Note:** Objects currently being used (with {@link UsageMarker}) are protected from deletion.
+ *
+ * @example Make an object deletable
+ * ```ts
+ * const deletable = spawnedObject.addComponent(Deletable);
+ * // Object can now be destroyed by entering a DeleteBox
+ * ```
+ *
+ * @summary Marks object as destroyable by DeleteBox
  * @category Interactivity
  * @group Components
+ * @see {@link DeleteBox} for the deletion trigger
+ * @see {@link UsageMarker} for protecting objects in use
  */
 export declare class Deletable extends Component {
     update(): void;
 }
 
 /**
- * A box-shaped area that can be used to delete objects that get into it. Useful for sandbox-style builders or physics simulations.
+ * DeleteBox creates an invisible deletion zone that destroys objects entering it.
+ * Works with objects that have a {@link Deletable} component attached.
+ *
+ * ![](https://cloud.needle.tools/-/media/J-Gmdhl214kfdjkfYViG8g.gif)
+ *
+ * **Use cases:**
+ * - Trash bins in sandbox builders
+ * - Kill zones in physics simulations
+ * - Cleanup areas for multiplayer scenes
+ *
+ * **Setup:**
+ * 1. Add DeleteBox to a GameObject with a BoxCollider-like shape
+ * 2. Add {@link Deletable} component to objects that should be destroyable
+ * 3. Objects entering the box will be destroyed (synced across network)
+ *
+ * **Debug:** Use `?debugdeletable` URL parameter to visualize deletion areas.
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
+ *
+ * @example Create a deletion zone
+ * ```ts
+ * const trashBin = trashBinModel.addComponent(DeleteBox);
+ * // Objects with Deletable component will be destroyed when entering
+ * ```
  *
  * @summary Box area that deletes objects entering it
  * @category Interactivity
  * @group Components
+ * @see {@link Deletable} - Add to objects that can be destroyed
+ * @see {@link Duplicatable} for spawning objects
+ * @see {@link DragControls} for moving objects
  */
 export declare class DeleteBox extends BoxHelperComponent {
     static _instances: DeleteBox[];
@@ -4286,6 +4729,28 @@ declare enum DepthOfFieldMode {
 
 export declare function deserializeObject(obj: ISerializable, serializedData: object, context: SerializationContext): boolean;
 
+/**
+ * Destroys a GameObject or Component, removing it from the scene and cleaning up resources.
+ * Calls `onDisable()` and `onDestroy()` lifecycle methods on all affected components.
+ *
+ * @param instance The Object3D or Component to destroy
+ * @param recursive If true (default), also destroys all children recursively
+ * @param dispose If true, also disposes GPU resources (geometries, materials, textures)
+ *
+ * @example Destroy an object
+ * ```ts
+ * import { destroy } from "@needle-tools/engine";
+ * destroy(this.gameObject);
+ * ```
+ *
+ * @example Destroy with resource disposal
+ * ```ts
+ * destroy(myObject, true, true); // recursive + dispose GPU resources
+ * ```
+ *
+ * @see {@link GameObject.destroy} for the static method equivalent
+ * @see {@link setDontDestroy} to mark objects as non-destroyable
+ */
 export declare function destroy(instance: Object3D | IComponent, recursive?: boolean, dispose?: boolean): void;
 
 export declare function destroyComponentInstance(componentInstance: IComponent): void;
@@ -4293,12 +4758,31 @@ export declare function destroyComponentInstance(componentInstance: IComponent):
 export declare function determineMimeTypeFromExtension(name: string): NeedleMimetype | null;
 
 /**
- * Enables or disables the GameObject based on the device type (mobile or desktop).
- * You can use this to show or hide objects depending on whether the user is on a mobile device or a desktop.
+ * DeviceFlag shows or hides GameObjects based on device type.
+ * Use for responsive 3D content - show different UI, models, or interactions
+ * depending on mobile vs desktop.
+ *
+ * **Device types:**
+ * - `Desktop` - Traditional computers with mouse/keyboard
+ * - `Mobile` - Phones and tablets with touch input
+ * - Combine with bitwise OR for multiple: `Desktop | Mobile`
+ *
+ * @example Show only on desktop
+ * ```ts
+ * const flag = myObject.addComponent(DeviceFlag);
+ * flag.visibleOn = DeviceType.Desktop;
+ * ```
+ *
+ * @example Show on both mobile and desktop
+ * ```ts
+ * flag.visibleOn = DeviceType.Desktop | DeviceType.Mobile;
+ * ```
  *
  * @summary Show or hide GameObject based on device type
  * @category Utilities
  * @group Components
+ * @see {@link DeviceType} for device options
+ * @see {@link XRFlag} for XR-based visibility
  */
 export declare class DeviceFlag extends Component {
     visibleOn: DeviceType;
@@ -4351,11 +4835,15 @@ export declare namespace DeviceUtilities {
 }
 
 /**
- * The wrap mode of the {@link PlayableDirector}.
+ * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
+ * @see {@link PlayableDirector.extrapolationMode}
  */
 declare enum DirectorWrapMode {
+    /** Hold the last frame when playback reaches the end of the timeline. */
     Hold = 0,
+    /** Loop back to the start and continue playing indefinitely. */
     Loop = 1,
+    /** Stop playback when the end is reached. The timeline will not loop. */
     None = 2
 }
 
@@ -4379,12 +4867,42 @@ export declare class DocumentExtension implements IUSDExporterExtension {
 }
 
 /**
- * DragControls allows you to drag objects around in the scene. It can be used to move objects in 2D (screen space) or 3D (world space).
- * Debug mode can be enabled with the URL parameter `?debugdrag`, which shows visual helpers and logs drag operations.
+ * [DragControls](https://engine.needle.tools/docs/api/DragControls) enables interactive dragging of objects in 2D (screen space) or 3D (world space).
+ *
+ * ![](https://cloud.needle.tools/-/media/HyrtRDLjdmndr23_SR4mYw.gif)
+ *
+ * **Drag modes:**
+ * - `XZPlane` - Drag on horizontal plane (good for floor objects)
+ * - `Attached` - Follow pointer directly (screen plane in 2D, controller in XR)
+ * - `HitNormal` - Drag along the surface normal where clicked
+ * - `DynamicViewAngle` - Auto-switch between XZ and screen based on view angle
+ * - `SnapToSurfaces` - Snap to scene geometry while dragging
+ *
+ * **Features:**
+ * - Works across desktop, mobile, VR, and AR
+ * - Optional grid snapping (`snapGridResolution`)
+ * - Rotation preservation (`keepRotation`)
+ * - Automatic networking with {@link SyncedTransform}
+ *
+ *
+ * **Debug:** Use `?debugdrag` URL parameter for visual helpers.
+ *
+ * @example Basic draggable object
+ * ```ts
+ * const drag = myObject.addComponent(DragControls);
+ * drag.dragMode = DragMode.XZPlane;
+ * drag.snapGridResolution = 0.5; // Snap to 0.5 unit grid
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
  *
  * @summary Enables dragging of objects in 2D or 3D space
  * @category Interactivity
  * @group Components
+ * @see {@link DragMode} for available drag behaviors
+ * @see {@link Duplicatable} for drag-to-duplicate functionality
+ * @see {@link SyncedTransform} for networked dragging
+ * @see {@link ObjectRaycaster} for pointer detection
  */
 export declare class DragControls extends Component implements IPointerEventHandler {
     /**
@@ -4514,40 +5032,52 @@ export declare enum DragMode {
     None = 5
 }
 
-/** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene
- * It can be used to allow users to drag and drop glTF files into the scene to add new objects.
- * Existing child objects will behave like placeholders and will be removed when new files are dropped.
+/**
+ * DropListener enables drag-and-drop loading of 3D files directly into your scene.
+ * Users can drop glTF/GLB files onto the canvas to dynamically add new objects at runtime.
  *
- * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
- * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
+ * [![](https://cloud.needle.tools/-/media/p5LNPTQ0u4mRXA6WiSmzIQ.gif)](https://engine.needle.tools/samples/droplistener)
  *
- * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
+ * **Supported formats:** glTF, GLB, FBX, OBJ, USDZ, VRM
  *
- * The following events are dispatched by the DropListener:
- * - **object-added** - dispatched when a new object is added to the scene
- * - **file-dropped** - dispatched when a file is dropped into the scene
+ * **Key features:**
+ * - Drop files directly onto canvas or onto a specific {@link dropArea}
+ * - Paste URLs from clipboard (Ctrl/Cmd+V)
+ * - Auto-fit objects to a specific size with {@link fitIntoVolume}
+ * - Network sync to share dropped objects with other users
+ * - Special handling for GitHub and Polyhaven URLs
  *
- * @example
- * ```typescript
- * import { DropListener, DropListenerEvents } from "@needle-tools/engine";
+ * **Events:**
+ * - `file-dropped` - Fired for each dropped file
+ * - `object-added` - Fired when object is loaded and added to scene
  *
- * const dropListener = new DropListener();
+ * **Debug:** Use `?debugdroplistener` URL parameter
  *
- * gameObject.addComponent(dropListener);
- * dropListener.on(DropListenerEvents.FileDropped, (evt) => {
- *   console.log("File dropped", evt.detail);
- *   const file = evt.detail as File;
- * });
+ * @example Listen for dropped objects
+ * ```ts
+ * const dropListener = myObject.addComponent(DropListener);
+ * dropListener.useNetworking = true;
+ * dropListener.fitIntoVolume = true;
  *
  * dropListener.on(DropListenerEvents.ObjectAdded, (evt) => {
- *    console.log("Object added", evt.detail);
- *    const gltf = evt.detail as GLTF;
+ *   const { object, model } = evt.detail;
+ *   console.log("Added:", object.name);
  * });
  * ```
  *
- * @summary Component to handle drag and drop of files into the scene
+ * @example Load from URL programmatically
+ * ```ts
+ * const obj = await dropListener.loadFromURL("https://example.com/model.glb");
+ * ```
+ * Hint: We recommend to use {@link AssetReference} for preloading and referencing assets in code if you simply want to load a model.
+ *
+ * @summary Drag-and-drop file loading for 3D assets
  * @category Asset Management
  * @group Components
+ * @see {@link SceneSwitcher} for loading entire scenes
+ * @see {@link AssetReference} for preloading assets
+ * @see {@link SyncedTransform} for networking support
+ * @link https://engine.needle.tools/samples/droplistener for a live demo
  */
 export declare class DropListener extends Component {
     /**
@@ -4723,21 +5253,52 @@ export declare type DropListenerOnDropArguments = {
 };
 
 /**
- * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.
+ * The Duplicatable component creates clones of a GameObject when clicked/tapped/dragged.
+ * Perfect for spawning objects, creating drag-and-drop inventories, or multiplayer object creation.
+ *
+ * ![](https://cloud.needle.tools/-/media/J_ij9vxhh1zhS8h2ftGBXQ.gif)
+ *
+ * **How it works:**
+ * - When the user clicks on this object, it creates a clone of the assigned `object`
+ * - The clone is automatically set up with {@link DragControls} so users can drag it
+ * - If networking is enabled, clones are synced via {@link SyncedTransform}
+ * - Rate limiting prevents spam (controlled by `limitCount`)
+ *
+ * **Setup tips:**
+ * - Assign `object` to a template object (it will be hidden and used as source)
+ * - If `object` is not assigned, the component's own GameObject is used as template
+ * - Add an {@link ObjectRaycaster} to enable pointer detection (added automatically if missing)
+ *
+ * @example Basic duplicatable button
+ * ```ts
+ * const duplicatable = spawnButton.addComponent(Duplicatable);
+ * duplicatable.object = templateObject; // Object to clone
+ * duplicatable.parent = spawnContainer;  // Where to place clones
+ * duplicatable.limitCount = 10;          // Max 10 per second
+ * ```
  *
  * @summary Duplicates a GameObject on pointer events
  * @category Interactivity
  * @group Components
+ * @see {@link DragControls} for dragging the duplicated objects
+ * @see {@link SyncedTransform} for networking support
+ * @see {@link GameObject.instantiateSynced} for the underlying instantiation
+ * @link https://engine.needle.tools/samples/collaborative-sandbox/
  */
 export declare class Duplicatable extends Component implements IPointerEventHandler {
-    /** Duplicates will be parented into the set object. If not defined, this GameObject will be used as parent. */
+    /**
+     * Parent object for spawned duplicates.
+     * If not set, duplicates are parented to this GameObject's parent.
+     */
     parent: GameObject | null;
-    /** The object to be duplicated. If no object is assigned then the object the Duplicatable component is attached to will be used for cloning.
-     * @default null
+    /**
+     * Template object to duplicate. This object will be hidden and used as the source for clones.
+     * If not assigned, this GameObject itself is used as the template.
      */
     object: GameObject | null;
     /**
-     * The maximum number of objects that can be duplicated in the interval.
+     * Maximum duplications allowed per second to prevent spam.
+     * The counter decreases by 1 each second.
      * @default 60
      */
     limitCount: number;
@@ -4832,24 +5393,49 @@ declare class EulerSerializer extends TypeSerializer {
 }
 
 /**
- * The EventList is a class that can be used to create a list of event listeners that can be invoked.
+ * EventList manages a list of callbacks that can be invoked together.
+ * Used for Unity-style events that can be configured in the editor (Unity or Blender).
  *
- * @example
+ * **Serialization:**
+ * EventLists are serializable - callbacks configured in Unity/Blender will work at runtime.
+ * Mark fields with `@serializable(EventList)` for editor support.
+ *
+ * **Usage patterns:**
+ * - Button click handlers
+ * - Animation events
+ * - Custom component callbacks
+ * - Scene loading events
+ *
+ * ![](https://cloud.needle.tools/-/media/P7bEKQvfgRUMTb2Wi1hWXg.png)
+ * *Screenshot of a Unity component with an EventList field*
+ *
+ * ![](https://cloud.needle.tools/-/media/i2hi2OHfbaDyHyBL6Gt58A.png)
+ * *Screenshot of a Blender component with an EventList field*
+ *
+ * @example Create and use an EventList
  * ```ts
- * // create an event list
- * const onClick = new EventList<(event: MouseEvent) => void>();
+ * // Define in your component
+ * @serializable(EventList)
+ * onClick: EventList = new EventList();
  *
- * // add an event listener
- * onClick.addEventListener((event) => {
- *   console.log("Clicked!", event);
- * });
+ * // Add listeners
+ * this.onClick.addEventListener(() => console.log("Clicked!"));
  *
- * // invoke the event list
- * onClick.invoke(new MouseEvent("click"));
+ * // Invoke all listeners
+ * this.onClick.invoke();
+ * ```
+ *
+ * @example Listen with arguments
+ * ```ts
+ * const onScore = new EventList<{ points: number }>();
+ * onScore.addEventListener(data => console.log("Scored:", data.points));
+ * onScore.invoke({ points: 100 });
  * ```
  *
  * @category Events
  * @group Utilities
+ * @see {@link CallInfo} for individual callback configuration
+ * @see {@link Button} for UI button events
  */
 export declare class EventList<TArgs extends any = any> implements IEventList {
     /** checked during instantiate to create a new instance */
@@ -5332,10 +5918,25 @@ declare type FitParameters = {
 };
 
 /**
- * The FixedJoint groups together 2 rigidbodies, making them stick together in their bound position
- * @summary Connect two Rigidbodies and make them stick together
+ * FixedJoint locks two {@link Rigidbody} components together, making them move as one rigid unit.
+ * The bodies maintain their relative position and rotation at the time the joint is created.
+ *
+ * Use this for:
+ * - Attaching objects together permanently
+ * - Creating compound rigid bodies
+ * - Welding broken pieces back together
+ *
+ * @example Attach a weapon to a character
+ * ```ts
+ * const joint = weapon.addComponent(FixedJoint);
+ * joint.connectedBody = characterRigidbody;
+ * ```
+ *
+ * @summary Lock two Rigidbodies together rigidly
  * @category Physics
  * @group Components
+ * @see {@link Joint} base class
+ * @see {@link HingeJoint} for rotating connections
  */
 export declare class FixedJoint extends Joint {
     protected createJoint(self: Rigidbody, other: Rigidbody): void;
@@ -5361,11 +5962,46 @@ declare type FocusRectSettings = {
     zoom: number;
 };
 
-/* Excluded from this release type: Fog */
+/**
+ * Adds distance-based fog effect to the scene.
+ * When enabled, objects will fade into the fog color based on their distance from the camera.
+ *
+ * This component is automatically added to the scene when fog is enabled in the editor.
+ * For setting fog from code you can simply use `scene.fog = new Fog3(color, near, far)` without adding this component.
+ *
+ * @summary Adds fog effect to the scene
+ * @category Rendering
+ * @group Components
+ * @link https://threejs.org/docs/#Fog
+ */
+export declare class Fog extends Component {
+    /**
+     * The underlying Three.js Fog object. You can modify its properties directly for more advanced control.
+     * @remarks The Fog component provides convenient access to common fog properties like `near`, `far`, and `color`. Modifying those will update the underlying `fog` object accordingly. However, you can also access and modify the `fog` object directly for more advanced use cases, such as changing the fog mode or using a custom shader.
+     * @link https://threejs.org/docs/#Fog for available properties and methods on the Fog object.
+     */
+    get fog(): Fog_2;
+    get mode(): FogMode;
+    set near(value: number);
+    get near(): number;
+    set far(value: number);
+    get far(): number;
+    set color(value: Color);
+    get color(): Color;
+    private _fog?;
+    onEnable(): void;
+    onDisable(): void;
+}
 
+/**
+ * Fog rendering mode
+ */
 declare enum FogMode {
+    /** Linear fog increases uniformly with distance */
     Linear = 1,
+    /** Exponential fog increases exponentially with distance */
     Exponential = 2,
+    /** Exponential squared fog for denser falloff */
     ExponentialSquared = 3
 }
 
@@ -5376,6 +6012,22 @@ declare enum FontStyle {
     BoldAndItalic = 3
 }
 
+/**
+ * Iterates over all components on an Object3D and optionally its children.
+ * The callback can return a value to stop iteration early.
+ *
+ * @param instance The Object3D to iterate components on
+ * @param cb Callback function called for each component. Return a value to stop iteration.
+ * @param recursive If true (default), also iterates components on all children
+ * @returns The first non-undefined value returned by the callback, or undefined
+ *
+ * @example Find first Rigidbody in hierarchy
+ * ```ts
+ * const rb = foreachComponent(myObject, comp => {
+ *   if (comp instanceof Rigidbody) return comp;
+ * });
+ * ```
+ */
 export declare function foreachComponent(instance: Object3D, cb: ForEachComponentCallback, recursive?: boolean): any;
 
 declare type ForEachComponentCallback = (comp: IComponent) => any;
@@ -5384,15 +6036,31 @@ export declare function foreachComponentEnumerator<T extends IComponent>(instanc
 
 export declare function forward(obj: Object3D): Vector3;
 
+/**
+ * Represents the different phases of the update cycle in Needle Engine.
+ * Components can register for specific frame events to perform actions at precise moments.
+ * The order of execution is: Start → EarlyUpdate → Update → LateUpdate → OnBeforeRender → OnAfterRender
+ *
+ * @see {@link Component.startCoroutine} for using FrameEvent with coroutines
+ */
 export declare enum FrameEvent {
+    /** Called once when a component starts for the first time */
     Start = -1,
+    /** Called at the beginning of each frame, before the main update */
     EarlyUpdate = 0,
+    /** The main update phase, called once per frame */
     Update = 1,
+    /** Called after all Update callbacks have finished */
     LateUpdate = 2,
+    /** Called immediately before the scene is rendered */
     OnBeforeRender = 3,
+    /** Called after the scene has been rendered */
     OnAfterRender = 4,
+    /** Called before each physics simulation step */
     PrePhysicsStep = 9,
+    /** Called after each physics simulation step */
     PostPhysicsStep = 10,
+    /** Default value when no specific frame event is set */
     Undefined = -1
 }
 
@@ -5879,11 +6547,27 @@ export declare function getLoader(): INeedleGltfLoader;
 
 export declare function getOrAddComponent<T extends IComponent>(go: Object3D, typeName: ConstructorConcrete<T>, init?: ComponentInit<T>): T;
 
-/** Checks if a url parameter exists.
- * Returns true if it exists but has no value (e.g. ?help)
- * Returns false if it does not exist
- * Returns false if it's set to 0 e.g. ?debug=0
- * Returns the value if it exists e.g. ?message=hello
+/**
+ * Checks if a URL parameter exists and returns its value.
+ * Useful for debugging, feature flags, and configuration.
+ *
+ * @param paramName The URL parameter name to check
+ * @returns
+ * - `true` if the parameter exists without a value (e.g. `?debug`)
+ * - `false` if the parameter doesn't exist or is set to `0`
+ * - The numeric value if it's a number (e.g. `?level=5` returns `5`)
+ * - The string value otherwise (e.g. `?name=test` returns `"test"`)
+ *
+ * @example Check debug mode
+ * ```ts
+ * if (getParam("debug")) {
+ *   console.log("Debug mode enabled");
+ * }
+ * ```
+ * @example Get a numeric value
+ * ```ts
+ * const level = getParam("level"); // Returns number if ?level=5
+ * ```
  */
 export declare function getParam<T extends string>(paramName: T): Param<T>;
 
@@ -6197,11 +6881,27 @@ export declare class Graphic extends BaseUIComponent implements IGraphic, IRectT
 }
 
 /**
- * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).
+ * GraphicRaycaster enables pointer interactions with UI elements.
+ * Add this to a {@link Canvas} or UI hierarchy to enable button clicks,
+ * hover effects, and other UI interactions.
+ *
+ * **Requirements:**
+ * - Must be on the same object as a Canvas or on a parent
+ * - UI elements need proper RectTransform setup
+ *
+ * @example Enable UI interaction
+ * ```ts
+ * // Add to Canvas object
+ * canvas.addComponent(GraphicRaycaster);
+ * // Now buttons and other UI elements will respond to clicks
+ * ```
  *
  * @summary Raycaster for UI elements
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for UI root
+ * @see {@link Button} for clickable UI
+ * @see {@link EventSystem} for event handling
  */
 export declare class GraphicRaycaster extends ObjectRaycaster {
     constructor();
@@ -6243,11 +6943,27 @@ export declare class Graphics {
 }
 
 /**
- * GridHelper is a component that allows to display a grid in the scene.
+ * GridHelper displays a flat grid in the scene for visual reference.
+ * Useful for debugging, level design, or providing spatial context.
+ *
+ * ![](https://cloud.needle.tools/-/media/prWArU8xTbgBKWQOvhTOag.gif)
+ *
+ * **Properties:**
+ * - `color0` / `color1` - Alternating grid line colors
+ * - `isGizmo` - When true, only shows when gizmos are enabled
+ *
+ * @example Add a grid to the scene
+ * ```ts
+ * const grid = myObject.addComponent(GridHelper);
+ * grid.color0 = new Color(0.3, 0.3, 0.3);
+ * grid.color1 = new Color(0.5, 0.5, 0.5);
+ * ```
  *
- * @example Display a grid in the scene
  * @category Helpers
  * @group Components
+ * @see {@link Gizmos} for debug visualization
+ *
+ * ![](https://cloud.needle.tools/-/media/i5KGKBUQ3iAX9h6o_9EY2w.jpg)
  */
 export declare class GridHelper extends Component {
     isGizmo: boolean;
@@ -6270,13 +6986,35 @@ export declare class GridLayoutGroup extends LayoutGroup {
 }
 
 /**
- * GroundProjectedEnv creates a ground projection of the current environment map.
+ * GroundProjectedEnv projects the environment map onto a virtual ground plane.
+ * Creates a realistic floor from 360° panoramas/HDRIs by deforming the skybox
+ * into a hemisphere with a beveled floor.
+ *
+ *
+ * [![](https://cloud.needle.tools/-/media/8LDMd4TnGxVIj1XOfxIUIA.gif)](https://engine.needle.tools/samples/ground-projection)
+ *
+ * **Key properties:**
+ * - `radius` - Size of the projection sphere (keep camera inside)
+ * - `height` - How high the original photo was taken (affects floor magnification)
+ * - `autoFit` - Automatically center and position at ground level
+ * - `arBlending` - Blend with real-world in AR (0=hidden, 1=visible)
  *
- * - Example https://engine.needle.tools/samples/ground-projection
+ * **Debug:** Use `?debuggroundprojection` URL parameter.
+ *
+ * @example Apply ground projection
+ * ```ts
+ * const ground = myObject.getComponent(GroundProjectedEnv);
+ * ground.radius = 100;
+ * ground.height = 2;
+ * ground.apply();
+ * ```
  *
  * @summary Projects the environment map onto the ground
  * @category Rendering
  * @group Components
+ * @see {@link Camera} for environment/skybox settings
+ * @see {@link ContactShadows} for ground shadows
+ * @link https://engine.needle.tools/samples/ground-projection for a demo of ground projection
  */
 export declare class GroundProjectedEnv extends Component {
     /**
@@ -6389,15 +7127,33 @@ export declare class HideOnStart extends Component implements UsdzBehaviour {
 }
 
 /**
- * The HingeJoint groups together 2 rigid bodies, constraining them to move like connected by a hinge.
+ * HingeJoint connects two {@link Rigidbody} components with a rotating constraint,
+ * like a door hinge or wheel axle. Bodies can only rotate around the specified axis.
  *
- * You can specify the anchor point and axis of rotation for the hinge.
- * @summary Connect two Rigidbodies with a hinge
- * @category Physics
+ * Use this for:
+ * - Doors and gates
+ * - Wheels and axles
+ * - Pendulums
+ * - Any rotating mechanical connection
+ *
+ * @example Create a door hinge
+ * ```ts
+ * const hinge = door.addComponent(HingeJoint);
+ * hinge.connectedBody = doorFrameRigidbody;
+ * hinge.anchor = new Vector3(0, 0, 0); // Hinge position
+ * hinge.axis = new Vector3(0, 1, 0);   // Rotate around Y axis
+ * ```
+ *
+ * @summary Connect two Rigidbodies with a rotating hinge
+ * @category Physics
  * @group Components
+ * @see {@link Joint} base class
+ * @see {@link FixedJoint} for rigid connections
  */
 export declare class HingeJoint extends Joint {
+    /** Local position of the hinge pivot point */
     anchor?: Vector3;
+    /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
     axis?: Vector3;
     protected createJoint(self: Rigidbody, other: Rigidbody): void;
 }
@@ -6755,12 +7511,31 @@ declare interface ILightDataRegistry {
 /* Excluded from this release type: ILoadingViewHandler */
 
 /**
- * Image is a UI component that displays a sprite (2D image) in the user interface.
- * You can set the image property to assign a texture to be displayed.
- * The sprite can be customized with various properties such as color tinting and pixel density.
+ * Image displays a sprite (2D texture) in the UI. Can be used for icons,
+ * backgrounds, or any visual element that needs a texture.
+ *
+ * **Properties:**
+ * - `image` - Direct texture assignment (convenience property)
+ * - `sprite` - Sprite object containing texture and rect info
+ * - `color` - Tint color applied to the image (inherited from Graphic)
+ *
+ * **Usage with Button:**
+ * Image is commonly paired with {@link Button} to create clickable
+ * UI elements with visual feedback via color tinting.
+ *
+ * @example Set an image texture
+ * ```ts
+ * const img = myIcon.getComponent(Image);
+ * img.image = myTexture;
+ * img.color = new RGBAColor(1, 0.5, 0.5, 1); // Red tint
+ * ```
+ *
  * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for the UI root
+ * @see {@link Button} for clickable images
+ * @see {@link RawImage} for non-UI image display
  */
 declare class Image_2 extends MaskableGraphic {
     set image(img: Texture | null);
@@ -6939,7 +7714,50 @@ export declare class InheritVelocityModule {
 }
 
 /**
- * The input system is responsible for handling all input events like pointer events (mouse, touch, xr controllers) and keyboard events.
+ * Handles all input events including mouse, touch, keyboard, and XR controllers.
+ * Access via `this.context.input` from any component.
+ *
+ * @example Checking mouse/pointer state
+ * ```ts
+ * update() {
+ *   if (this.context.input.mouseDown) {
+ *     console.log("Mouse button pressed");
+ *   }
+ *   if (this.context.input.mouseClick) {
+ *     console.log("Click detected");
+ *   }
+ *   const pos = this.context.input.mousePosition;
+ *   console.log(`Mouse at: ${pos.x}, ${pos.y}`);
+ * }
+ * ```
+ * @example Keyboard input
+ * ```ts
+ * update() {
+ *   if (this.context.input.isKeyDown("Space")) {
+ *     console.log("Space pressed this frame");
+ *   }
+ *   if (this.context.input.isKeyPressed("w")) {
+ *     console.log("W key is held down");
+ *   }
+ * }
+ * ```
+ * @example Event-based input
+ * ```ts
+ * onEnable() {
+ *   this.context.input.addEventListener("pointerdown", this.onPointerDown);
+ * }
+ * onDisable() {
+ *   this.context.input.removeEventListener("pointerdown", this.onPointerDown);
+ * }
+ * onPointerDown = (evt: NEPointerEvent) => {
+ *   console.log("Pointer down:", evt.pointerId);
+ * }
+ * ```
+ *
+ * @see {@link NEPointerEvent} for pointer event data
+ * @see {@link InputEvents} for available event types
+ * @see {@link PointerType} for pointer device types
+ * @link https://engine.needle.tools/docs/scripting.html
  */
 export declare class Input implements IInput {
     /** This is a list of event listeners per event type (e.g. pointerdown, pointerup, keydown...). Each entry contains a priority and list of listeners.
@@ -6951,7 +7769,7 @@ export declare class Input implements IInput {
      * @param type The event type to listen for
      * @param callback The callback to call when the event is triggered
      * @param options The options for adding the event listener.
-     * @example Basic usage:
+     * @example Basic usage
      * ```ts
      * input.addEventListener("pointerdown", (evt) => {
      *   console.log("Pointer down", evt.pointerId, evt.pointerType);
@@ -6967,7 +7785,7 @@ export declare class Input implements IInput {
      * @example Adding a listener that is only called once
      * ```ts
      * input.addEventListener("pointerdown", (evt) => {
-     * console.log("Pointer down", evt.pointerId, evt.pointerType);
+     *   console.log("Pointer down", evt.pointerId, evt.pointerType);
      * }, { once: true });
      * ```
      */
@@ -7165,12 +7983,23 @@ export declare enum InputEventQueue {
     Late = 100
 }
 
+/**
+ * Event types that can be listened to via {@link Input.addEventListener}.
+ * @see {@link NEPointerEvent} for pointer event data
+ * @see {@link NEKeyboardEvent} for keyboard event data
+ */
 export declare const enum InputEvents {
+    /** Fired when a pointer button is pressed */
     PointerDown = "pointerdown",
+    /** Fired when a pointer button is released */
     PointerUp = "pointerup",
+    /** Fired when a pointer moves */
     PointerMove = "pointermove",
+    /** Fired when a key is pressed down */
     KeyDown = "keydown",
+    /** Fired when a key is released */
     KeyUp = "keyup",
+    /** Fired when a key produces a character value */
     KeyPressed = "keypress"
 }
 
@@ -7368,6 +8197,40 @@ export declare class InstancingUtil {
     static markDirty(go: Object3D | null, recursive?: boolean): void;
 }
 
+/**
+ * Creates a copy (clone) of a GameObject or loads and instantiates an AssetReference.
+ * All components on the original object are cloned and `awake()` is called on them.
+ *
+ * @param instance The Object3D to clone, or an AssetReference to load and instantiate
+ * @param opts Optional instantiation settings (position, rotation, scale, parent)
+ * @returns The cloned GameObject, or a Promise<Object3D> if instantiating from AssetReference
+ *
+ * @example Clone an object
+ * ```ts
+ * import { instantiate } from "@needle-tools/engine";
+ * const clone = instantiate(original);
+ * clone.position.set(1, 0, 0);
+ * this.context.scene.add(clone);
+ * ```
+ *
+ * @example Instantiate with options
+ * ```ts
+ * const clone = instantiate(original, {
+ *   parent: parentObject,
+ *   position: new Vector3(0, 1, 0),
+ *   rotation: new Quaternion()
+ * });
+ * ```
+ *
+ * @example Instantiate from AssetReference
+ * ```ts
+ * const instance = await instantiate(myAssetRef);
+ * if (instance) this.context.scene.add(instance);
+ * ```
+ *
+ * @see {@link GameObject.instantiate} for the static method equivalent
+ * @see {@link destroy} to remove instantiated objects
+ */
 export declare function instantiate(instance: AssetReference, opts?: IInstantiateOptions | null): Promise<Object3D | null>;
 
 export declare function instantiate(instance: IGameObject | Object3D, opts?: IInstantiateOptions | null): IGameObject;
@@ -7979,7 +8842,17 @@ export declare interface ITime {
 }
 
 /**
- * Experimental interface for receiving timeline animation callbacks. Register at the PlayableDirector
+ * Interface for receiving callbacks during timeline animation evaluation.
+ * Allows modification of position/rotation values before they are applied.
+ *
+ * **Registration:**
+ * ```ts
+ * director.registerAnimationCallback(this);
+ * // Later: director.unregisterAnimationCallback(this);
+ * ```
+ *
+ * @experimental This interface may change in future versions
+ * @see {@link PlayableDirector.registerAnimationCallback}
  */
 export declare interface ITimelineAnimationOverride {
     /**
@@ -8053,12 +8926,22 @@ export declare class JoinedRoomResponse {
 }
 
 /**
- * Base class for physics joints connecting two rigid bodies.
- * @summary Connect two Rigidbodies
+ * Base class for physics joints that connect two {@link Rigidbody} components.
+ * Joints constrain how two bodies can move relative to each other.
+ *
+ * The joint is created between:
+ * - The {@link Rigidbody} on this GameObject (automatically found)
+ * - The {@link connectedBody} Rigidbody you specify
+ *
+ * @summary Connect two Rigidbodies with physics constraints
  * @category Physics
  * @group Components
+ * @see {@link FixedJoint} for rigid connections
+ * @see {@link HingeJoint} for rotating connections
+ * @see {@link Rigidbody} for physics bodies
  */
 declare abstract class Joint extends Component {
+    /** The other Rigidbody to connect to */
     connectedBody?: Rigidbody;
     get rigidBody(): Rigidbody | null;
     private _rigidBody;
@@ -8162,16 +9045,38 @@ declare type LifecycleMethodOptions = {
 };
 
 /**
- * The Light component creates a light source in the scene.
- * Supports directional, spot, and point light types with various customization options.
- * Lights can cast shadows with configurable settings and can be set to baked or realtime rendering.
+ * Light component creates a light source in the scene for illuminating 3D objects.
+ *
+ * **Light types:**
+ * - `Directional` - Sun-like parallel rays (best for outdoor scenes)
+ * - `Point` - Omnidirectional from a point (bulbs, candles)
+ * - `Spot` - Cone-shaped (flashlights, stage lights)
  *
- * Debug mode can be enabled with the URL parameter `?debuglights`, which shows
- * additional console output and visual helpers for lights.
+ * **Shadows:**
+ * Enable shadows via `shadows` property. Configure quality with shadow resolution
+ * settings. Directional lights support adaptive shadow cascades.
+ *
+ * **Performance tips:**
+ * - Use baked lighting (`lightmapBakeType = Baked`) when possible
+ * - Limit shadow-casting lights (1-2 recommended)
+ * - Reduce shadow resolution for mobile
+ *
+ * **Debug:** Use `?debuglights` URL parameter for visual helpers.
+ *
+ * @example Configure a directional light
+ * ```ts
+ * const light = myLight.getComponent(Light);
+ * light.intensity = 1.5;
+ * light.color = new Color(1, 0.95, 0.9); // Warm white
+ * light.shadows = LightShadows.Soft;
+ * ```
  *
  * @summary Light component for various light types and shadow settings
  * @category Rendering
  * @group Components
+ * @see {@link LightType} for available light types
+ * @see {@link ReflectionProbe} for environment reflections
+ * @see {@link Camera} for rendering configuration
  */
 export declare class Light extends Component implements ILight {
     /**
@@ -8420,26 +9325,36 @@ declare type LoadSceneEvent = {
  */
 export declare function loadSync(context: Context, url: string, sourceId: string, seed: number | UIDProvider | null, prog?: (ProgressEvent: any) => void): Promise<Model | undefined>;
 
-declare enum LODFadeMode {
-    None = 0,
-    CrossFade = 1,
-    SpeedTree = 2
-}
-
 /**
- * LODGroup allows to create a group of LOD levels for an object.
+ * LODGroup manages multiple levels of detail for optimized rendering.
+ * Objects switch between different detail levels based on distance from camera.
+ *
+ * LOD levels are defined in {@link LODModel} objects, each specifying:
+ * - The distance at which that level becomes active
+ * - The {@link Renderer} components to show at that level
+ *
+ * This is useful for performance optimization - showing high-detail models up close
+ * and lower-detail versions at distance where the difference isn't visible.
+ *
+ * **Progressive Loading:**
+ * For automatic texture/mesh LOD streaming, see the `@needle-tools/gltf-progressive` package
+ * which provides progressive loading capabilities independent of this component.
+ *
+ * **Debug options:**
+ * - `?debuglods` - Log LOD switching information
+ * - `?nolods` - Disable LOD system entirely
  *
  * @summary Level of Detail Group for optimizing rendering
  * @category Rendering
  * @group Components
+ * @see {@link LODModel} for configuring individual LOD levels
+ * @see {@link Renderer} for the renderers controlled by LOD
+ * @see {@link LODsManager} for programmatic control of progressive LODs
+ * @link https://npmjs.com/package/@needle-tools/gltf-progressive
  */
 export declare class LODGroup extends Component {
-    fadeMode: LODFadeMode;
-    localReferencePoint: Vector3 | undefined;
-    lodCount: number;
-    size: number;
-    animateCrossFading: boolean;
-    lodModels?: LODModel[];
+    /** Array of LOD level configurations */
+    readonly lodModels: LODModel[];
     private _lods;
     private _settings;
     private _lodsHandler?;
@@ -8447,12 +9362,25 @@ export declare class LODGroup extends Component {
     onAfterRender(): void;
     private onAddLodLevel;
     private _distanceFactor;
+    /**
+     * Adjusts all LOD transition distances by a multiplier.
+     * Values > 1 push LOD transitions further away (higher quality at distance).
+     * Values < 1 bring transitions closer (better performance).
+     * @param factor Multiplier to apply to all LOD distances
+     */
     distanceFactor(factor: number): void;
 }
 
+/**
+ * Defines a single LOD level with its transition distance and associated renderers.
+ * Used by {@link LODGroup} to configure level of detail switching.
+ */
 export declare class LODModel {
+    /** Screen height ratio (0-1) at which this LOD becomes active */
     screenRelativeTransitionHeight: number;
+    /** Distance from camera at which this LOD becomes active */
     distance: number;
+    /** Renderers to show at this LOD level */
     renderers: Renderer[];
 }
 
@@ -8530,28 +9458,43 @@ export declare class LookAt extends Component implements UsdzBehaviour {
 }
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
- * This component is used by {@link OrbitControls} internally.
+ * LookAtConstraint component is primarely used by {@link OrbitControls} to set the camera's focus point.
+ * It does not have its own logic to update the look-at position.
+ *
+ * The constraint uses a list of source objects - the look-at target is
+ * calculated from the first source in the `sources` array.
  *
- * @summary Look At Constraint for OrbitControls
+ * **Integration with OrbitControls:**
+ * When attached to the same GameObject as OrbitControls, this constraint
+ * controls where the camera orbits around and looks at.
+ *
+ * @summary Look At Constraint for camera targeting
  * @category Camera and Controls
  * @group Components
+ * @see {@link OrbitControls} for camera orbit controls
+ * @see {@link SmoothFollow} for smooth position/rotation following
+ * @see {@link LookAt} for directly making an object look at a target without using a constraint
  */
 export declare class LookAtConstraint extends Component {
     /**
-     * When true the constraint is active.
+     * When true, the constraint is active and affects the target.
+     * Set to false to temporarily disable without removing sources.
      */
     constraintActive: boolean;
     /**
-     * When true the look at is locked to the position of the assigned sources.
+     * When true, the look-at position is locked and won't update
+     * even if source objects move.
      */
     locked: boolean;
     /**
-     * The sources to look at.
+     * Objects to look at. The first object in the array is used
+     * as the primary look-at target.
      */
     sources: Object3D[];
     /**
-     * Set the position of the constraint.
+     * Sets the world position that the constraint should look at.
+     * Updates the first source object's position.
+     * @param worldPosition The world-space position to look at
      */
     setConstraintPosition(worldPosition: Vector3): void;
 }
@@ -8694,20 +9637,89 @@ export declare class MaskableGraphic extends Graphic {
     protected onAfterCreated(): void;
 }
 
+export declare namespace MaterialX {
+    /**
+     * Utility function to load a MaterialX material from a URL. This can be used in your own code to load MaterialX materials outside of the glTF loading process. The URL should point to a MaterialX XML file.
+     */
+    export function loadFromUrl(urlOrXML: string, opts?: {
+        url?: string;
+        loadingManager?: LoadingManager;
+        materialNameOrIndex?: number | string;
+    }): Promise<Material | null>;
+}
+
 export declare const Mathf: MathHelper;
 
+/**
+ * Math utility class providing common mathematical operations.
+ * Access via the exported `Mathf` constant.
+ *
+ * @example
+ * ```ts
+ * import { Mathf } from "@needle-tools/engine";
+ *
+ * // Random number between 0 and 10
+ * const rand = Mathf.random(0, 10);
+ *
+ * // Clamp a value
+ * const clamped = Mathf.clamp(value, 0, 100);
+ *
+ * // Smooth interpolation
+ * const smoothed = Mathf.lerp(start, end, t);
+ * ```
+ */
 declare class MathHelper {
+    /**
+     * Returns a random number or element.
+     * @param arr Array to pick a random element from
+     * @returns Random element from array, or null if array is empty
+     * @example `Mathf.random([1, 2, 3])` - returns random element
+     */
     random<T>(arr: Array<T>): T | null;
+    /**
+     * Returns a random number between min and max (inclusive).
+     * @param min Minimum value (inclusive)
+     * @param max Maximum value (inclusive)
+     * @returns Random number in range, or 0-1 if no args provided
+     * @example `Mathf.random(0, 10)` - returns 0 to 10
+     */
     random(min?: number, max?: number): number;
+    /**
+     * Fills a Vector3 with random values.
+     * @param target Vector3 to fill with random values
+     * @param min Minimum value for each component
+     * @param max Maximum value for each component
+     */
     randomVector3(target: Vector3, min?: number, max?: number): void;
+    /**
+     * Clamps a value between min and max.
+     * @param value Value to clamp
+     * @param min Minimum bound
+     * @param max Maximum bound
+     * @returns Clamped value
+     */
     clamp(value: number, min: number, max: number): number;
+    /**
+     * Clamps a value between 0 and 1.
+     * @param value Value to clamp
+     * @returns Value clamped to [0, 1]
+     */
     clamp01(value: number): number;
     /**
-     * Linear interpolate
+     * Linearly interpolates between two values.
+     * @param value1 Start value (returned when t=0)
+     * @param value2 End value (returned when t=1)
+     * @param t Interpolation factor, clamped to [0, 1]
+     * @returns Interpolated value
      */
     lerp(value1: number, value2: number, t: number): number;
     /**
-     *
+     * Calculates the linear interpolation parameter that produces the given value.
+     * Inverse of lerp: if `lerp(a, b, t) = v`, then `inverseLerp(a, b, v) = t`
+     * @param value1 Start value
+     * @param value2 End value
+     * @param t The value to find the parameter for
+     * @returns The interpolation parameter (may be outside [0,1] if t is outside [value1, value2])
      */
     inverseLerp(value1: number, value2: number, t: number): number;
     /**
@@ -8719,6 +9731,14 @@ declare class MathHelper {
      * @param max2 The maximum value of the target range.
      */
     remap(value: number, min1: number, max1: number, min2: number, max2: number): number;
+    /**
+     * Moves a value towards a target by a maximum step amount.
+     * Useful for smooth following or gradual value changes.
+     * @param value1 Current value
+     * @param value2 Target value
+     * @param amount Maximum step to move (positive moves toward target)
+     * @returns New value moved toward target, never overshooting
+     */
     moveTowards(value1: number, value2: number, amount: number): number;
     readonly Rad2Deg: number;
     readonly Deg2Rad: number;
@@ -8734,7 +9754,20 @@ declare class MathHelper {
     tan(radians: number): number;
     gammaToLinear(gamma: number): number;
     linearToGamma(linear: number): number;
+    /**
+     * Checks if two vectors are approximately equal within epsilon tolerance.
+     * Works with Vector2, Vector3, Vector4, and Quaternion.
+     * @param v1 First vector
+     * @param v2 Second vector
+     * @param epsilon Tolerance for comparison (default: Number.EPSILON)
+     * @returns True if all components are within epsilon of each other
+     */
     approximately(v1: Vector, v2: Vector, epsilon?: number): boolean;
+    /**
+     * Easing function: slow start, fast middle, slow end (cubic).
+     * @param x Input value from 0 to 1
+     * @returns Eased value from 0 to 1
+     */
     easeInOutCubic(x: number): number;
 }
 
@@ -8742,6 +9775,8 @@ declare class MathHelper {
  * MeshCollider creates a collision shape from a mesh geometry.
  * Allows for complex collision shapes that match the exact geometry of an object.
  *
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
  * - Example: https://samples.needle.tools/physics-basic
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation
@@ -8914,6 +9949,15 @@ export declare namespace NEEDLE_ENGINE_FEATURE_FLAGS {
  * If a module is already loaded it's also available in the `MODULE` variable.
  */
 export declare namespace NEEDLE_ENGINE_MODULES {
+    export namespace MaterialX {
+        export type TYPE = needleToolsMaterialx;
+        let MODULE: TYPE;
+        let MAYBEMODULE: TYPE | null;
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        export function ready(): Promise<TYPE>;
+        /** Load the module */
+        export function load(): Promise<TYPE>;
+    }
     export namespace RAPIER_PHYSICS {
         export type TYPE = dimforgeRapier3dCompat;
         let MODULE: TYPE;
@@ -9349,15 +10393,37 @@ declare class NeedleGamepadButton {
 }
 
 /**
- * Provides configuration options for the built-in Needle Menu.
- * Needle Menu uses HTML in 2D mode, and automatically switches to a 3D menu in VR/AR mode.
+ * NeedleMenu provides configuration for the built-in UI menu.
+ * The menu renders as HTML overlay in browser mode and automatically
+ * switches to a 3D spatial menu in VR/AR.
+ *
+ * ![](https://cloud.needle.tools/-/media/YKleg1oPy_I8Hv8sg_k40Q.png)
+ *
+ * **Features:**
+ * - Fullscreen toggle button
+ * - Audio mute/unmute button
+ * - QR code sharing (desktop only)
+ * - Spatial menu in XR (appears when looking up)
+ * - Custom positioning (top/bottom)
+ *
+ * **Programmatic access:**
+ * Access the menu API via `this.context.menu` to add custom buttons,
+ * show/hide elements, or modify behavior at runtime.
  *
- * Controls display options, button visibility, and menu positioning.
- * From code, you can access the menu via {@link Context.menu}.
+ * @example Configure menu from code
+ * ```ts
+ * // Access the menu API
+ * this.context.menu.appendChild(myCustomButton);
+ * this.context.menu.setPosition("top");
+ * this.context.menu.showFullscreenOption(true);
+ * ```
  *
- * @summary Configuration component for the Needle Menu
+ * @summary Configuration component for the Needle Menu overlay
  * @category User Interface
  * @group Components
+ * @see {@link Context.menu} for programmatic menu control
+ * @see {@link Voip} adds a microphone button to the menu
+ * @see {@link ScreenCapture} adds a screen sharing button
  **/
 export declare class NeedleMenu extends Component {
     /**
@@ -9508,7 +10574,7 @@ export declare type NeedleMenuPostMessageModel = {
 /**
  * The supported file types that can be determined by the engine. Used in {@link tryDetermineMimetypeFromURL} and {@link tryDetermineMimetypeFromBinary}
  */
-export declare type NeedleMimetype = "unknown" | "unsupported" | "model/gltf+json" | "model/gltf-binary" | "model/vrm" | "model/vnd.usdz+zip" | "model/vnd.usd" | "model/vnd.usda" | "model/vnd.usdc" | "model/fbx" | "model/vnd.autodesk.fbx" | "model/obj" | (string & {});
+export declare type NeedleMimetype = "unknown" | "unsupported" | "model/gltf+json" | "model/gltf-binary" | "model/vrm" | "model/vnd.usdz+zip" | "model/vnd.usd" | "model/vnd.usda" | "model/vnd.usdc" | "model/fbx" | "model/vnd.autodesk.fbx" | "model/obj" | "application/materialx+xml" | (string & {});
 
 export declare const NeedlePatchesKey = "Needle:Patches";
 
@@ -10133,7 +11199,22 @@ export declare class NEKeyboardEvent extends KeyboardEvent {
 }
 
 /**
- * The Needle Engine Pointer Event is a custom event that extends the PointerEvent. It holds additional information like the device index, the origin of the event, the mode of the event (e.g. screen or spatial), the ray in world space, the space of the device, and more.
+ * Extended PointerEvent with Needle Engine-specific data.
+ * Contains information about the input device, spatial data for XR, and world-space ray.
+ *
+ * @example Accessing event data in a component
+ * ```ts
+ * onPointerDown(args: PointerEventData) {
+ *   const evt = args.event;
+ *   console.log(`Pointer ${evt.pointerId} (${evt.pointerType})`);
+ *   if (evt.isSpatial) {
+ *     console.log("XR input, ray:", evt.ray);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Input} for the input management system
+ * @see {@link PointerType} for available pointer types
  */
 export declare class NEPointerEvent extends PointerEvent {
     /**
@@ -10223,17 +11304,52 @@ export declare type NEPointerEventIntersection = Intersection & {
     event?: NEPointerEvent;
 };
 
-/** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)
- * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+/**
+ * NestedGltf loads and instantiates a glTF file when the component starts.
+ * NestedGltf components are created by the Unity exporter when nesting Objects with the GltfObject component (in Unity).
+ * Use this for lazy-loading content, modular scene composition, or dynamic asset loading.
+ *
+ * ![](https://cloud.needle.tools/-/media/lJKrr_2tWlqRFdFc46U4bQ.gif)
+ *
+ * The loaded glTF is instantiated as a sibling (child of parent) by default,
+ * inheriting the transform of the GameObject with this component.
+ *
+ * **Features:**
+ * - Automatic loading on start
+ * - Progress callbacks for loading UI
+ * - Preloading support for faster display
+ * - Event callback when loading completes
+ *
+ * @example Load a glTF when object becomes active
+ * ```ts
+ * const nested = myPlaceholder.addComponent(NestedGltf);
+ * nested.filePath = new AssetReference("models/furniture.glb");
+ * nested.loaded.addEventListener(({ instance }) => {
+ *   console.log("Loaded:", instance.name);
+ * });
+ * ```
+ *
+ * @example Preload for instant display
+ * ```ts
+ * // Preload during loading screen
+ * await nested.preload();
+ * // Later, when object becomes active, it displays instantly
+ * ```
  *
  * @summary Loads and instantiates a nested glTF file
  * @category Asset Management
  * @group Components
+ * @see {@link AssetReference} for asset loading utilities
+ * @see {@link SceneSwitcher} for scene-level loading
+ * @link https://engine.needle.tools/samples/hotspots
  */
 export declare class NestedGltf extends Component {
-    /**  A reference to the gltf file that should be loaded */
+    /** Reference to the glTF file to load. Can be a URL or asset path. */
     filePath?: AssetReference;
-    /** Invoked when the nested glTF file has been instantiated */
+    /**
+     * Event fired when the glTF has been loaded and instantiated.
+     * Provides the component, loaded instance, and asset reference.
+     */
     loaded: EventList<{
         component: NestedGltf;
         instance: any;
@@ -10263,9 +11379,45 @@ declare enum NEToneMappingMode {
 
 declare type NEToneMappingModeNames = keyof typeof NEToneMappingMode;
 
-/** Main class to communicate with the networking backend
- * @link https://engine.needle.tools/docs/networking.html
+/**
+ * Main class for multiuser networking. Access via `this.context.connection` from any component.
+ *
+ * **About GUIDs:**
+ * In Needle Engine networking, GUIDs (Globally Unique Identifiers) are used to identify objects and components across the network.
+ * Every GameObject and Component has a unique `guid` property that remains consistent across all clients.
+ * GUIDs are automatically assigned (e.g. during export from Unity/Blender) and are essential for:
+ * - Object ownership management (see {@link OwnershipModel})
+ * - State synchronization (storing and retrieving object state)
+ * - Identifying which object received a network message
+ *
+ * When working with networking, you'll typically use `this.guid` to identify your component or `this.gameObject.guid` for the GameObject.
+ *
+ * @example Joining a room
+ * ```ts
+ * this.context.connection.connect();
+ * this.context.connection.joinRoom("my-room");
+ * ```
+ * @example Listening to events
+ * ```ts
+ * this.context.connection.beginListen("my-event", (data) => {
+ *   console.log("Received:", data);
+ * });
+ * ```
+ * @example Sending data
+ * ```ts
+ * this.context.connection.send("my-event", { message: "Hello" });
+ * ```
+ * @example Using GUIDs for object identification
+ * ```ts
+ * // Get state for a specific object by its GUID
+ * const state = this.context.connection.tryGetState(this.guid);
  *
+ * // Delete remote state for an object
+ * this.context.connection.sendDeleteRemoteState(this.guid);
+ * ```
+ * @see {@link RoomEvents} for room lifecycle events
+ * @see {@link OwnershipModel} for object ownership
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
  */
 export declare class NetworkConnection implements INetworkConnection {
     private context;
@@ -10274,7 +11426,18 @@ export declare class NetworkConnection implements INetworkConnection {
     /** Experimental: networking via peerjs */
     get peer(): PeerNetworking;
     /**
-     * Returns the state of a given guid.
+     * Returns the cached network state for a given GUID.
+     * The state is stored locally whenever network updates are received for that object.
+     * @param guid The unique identifier of the object whose state you want to retrieve
+     * @returns The cached state object, or `null` if no state exists for this GUID
+     * @example
+     * ```ts
+     * // Get the last known state for this component
+     * const myState = this.context.connection.tryGetState(this.guid);
+     * if (myState) {
+     *   console.log("Found cached state:", myState);
+     * }
+     * ```
      */
     tryGetState(guid: string): IModel | null;
     /** The connection id of the local user - it is given by the networking backend and can not be changed */
@@ -10284,7 +11447,7 @@ export declare class NetworkConnection implements INetworkConnection {
      */
     get isDebugEnabled(): boolean;
     /**
-     * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `isInRoom` property.
+     * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `{@link isInRoom}` property.
      * @returns true if connected to the websocket.
      */
     get isConnected(): boolean;
@@ -10317,13 +11480,24 @@ export declare class NetworkConnection implements INetworkConnection {
     private _usersInRoomCopy;
     /** Returns a list of all user ids in the current room */
     usersInRoom(target?: string[] | null): string[];
-    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `SyncedRoom` component as well */
+    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `{@link SyncedRoom}` component as well */
     joinRoom(room: string, viewOnly?: boolean): boolean;
     /** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
     leaveRoom(room?: string | null): boolean;
     /** Send a message to the networking backend - it will broadcasted to all connected users in the same room by default */
     send<T extends WebsocketSendType>(key: string | OwnershipEvent, data?: T | null, queue?: SendQueue): void;
-    /** Use to delete state for a given guid on the server */
+    /**
+     * Deletes the network state for a specific object on the server.
+     * This removes the object's state from the room, preventing it from being sent to newly joining users.
+     * @param guid The unique identifier of the object whose state should be deleted
+     * @example
+     * ```ts
+     * // When destroying a networked object, clean up its server state
+     * onDestroy() {
+     *   this.context.connection.sendDeleteRemoteState(this.guid);
+     * }
+     * ```
+     */
     sendDeleteRemoteState(guid: string): void;
     /** Use to delete all state in the currently connected room on the server */
     sendDeleteRemoteStateAll(): void;
@@ -10333,7 +11507,7 @@ export declare class NetworkConnection implements INetworkConnection {
     private _defaultMessagesBufferArray;
     sendBufferedMessagesNow(): void;
     /** Use to start listening to networking events.
-     * To unsubscribe from events use the `stopListen` method.
+     * To unsubscribe from events use the `{@link stopListen}` method.
      * See the example below for typical usage:
      *
      * ### Component Example
@@ -10358,7 +11532,7 @@ export declare class NetworkConnection implements INetworkConnection {
     /**@deprecated please use stopListen instead (2.65.2-pre) */
     stopListening(key: (string & {}) | OwnershipEvent | OwnershipEventNamesIncoming | RoomEventsIncoming | RoomEvents, callback: Function | null): void;
     /** Use to stop listening to networking events
-     * To subscribe to events use the `beginListen` method.
+     * To subscribe to events use the `{@link beginListen}` method.
      * See the example below for typical usage:
      *
      * ### Component Example
@@ -10383,9 +11557,13 @@ export declare class NetworkConnection implements INetworkConnection {
     /** Use to stop listening to networking binary events */
     stopListenBinary(identifier: string, callback: any): void;
     private netWebSocketUrlProvider?;
-    /** Use to override the networking server backend url. This is what the `Networking` component uses to modify the backend url */
+    /** Use to override the networking server backend url.
+     * This is what the `{@link Networking}` component uses to modify the backend url.
+     **/
     registerProvider(prov: INetworkingWebsocketUrlProvider): void;
-    /** Used to connect to the networking server */
+    /** Used to connect to the networking server
+     * @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
+     */
     connect(url?: string): Promise<boolean>;
     /** Disconnect from the networking backend + reset internal state */
     disconnect(): void;
@@ -10643,10 +11821,22 @@ export declare type ObjectOptions = {
 };
 
 /**
- * A Raycaster that performs raycasting against its own GameObject.
+ * ObjectRaycaster enables pointer interactions with 3D objects.
+ * Add this component to any object that needs click/hover detection.
+ *
+ * **Usage:**
+ * Objects with ObjectRaycaster will receive pointer events when
+ * they implement interfaces like {@link IPointerClickHandler}.
+ *
+ * **Note:**
+ * In older Needle Engine versions the ObjectRaycaster was required to be added to the Scene.
+ * This is no longer the case - the EventSystem will automatically handle raycasts.
+ *
  *
  * @category Interactivity
  * @group Components
+ * @see {@link IPointerClickHandler} for click events
+ * @see {@link DragControls} for drag interactions
  */
 export declare class ObjectRaycaster extends Raycaster_2 {
     private targets;
@@ -10710,11 +11900,35 @@ export declare class ObjectUtils {
 /* Excluded from this release type: OffscreenCanvasExt */
 
 /**
- * OffsetConstraint component allows an object to maintain a specified positional and rotational offset
- * relative to another object, with options for alignment and leveling.
- * @summary Maintains positional and rotational offset relative to another object
+ * OffsetConstraint maintains a fixed positional and rotational offset relative to a target object.
+ * Useful for attaching objects to moving targets while preserving a specific spatial relationship.
+ *
+ * **Use cases:**
+ * - Camera following a player with offset
+ * - UI elements attached to characters
+ * - Weapons attached to hands
+ * - Objects orbiting around a target
+ *
+ * **Options:**
+ * - `affectPosition` - Apply position offset
+ * - `affectRotation` - Apply rotation offset
+ * - `alignLookDirection` - Make object face same direction as target
+ * - `levelLookDirection` - Keep look direction horizontal (ignore pitch)
+ * - `levelPosition` - Project position onto horizontal plane
+ * - `referenceSpace` - Transform offset in this object's coordinate space
+ *
+ * @example Attach camera offset to player
+ * ```ts
+ * const constraint = camera.addComponent(OffsetConstraint);
+ * // Configure via serialized properties in editor
+ * ```
+ *
+ * @summary Maintains positional/rotational offset relative to target
  * @category Constraints
  * @group Components
+ * @see {@link SmoothFollow} for smoothed following
+ * @see {@link LookAtConstraint} for aim constraints
+ * @see {@link AlignmentConstraint} for alignment between two objects
  */
 export declare class OffsetConstraint extends Component {
     private referenceSpace;
@@ -10996,12 +12210,50 @@ declare enum OpenURLMode {
     NewWindow = 2
 }
 
-/** The OrbitControls component is used to control a camera using the [OrbitControls from three.js](https://threejs.org/docs/#examples/en/controls/OrbitControls) library.
- * The three OrbitControls object can be accessed via the `controls` property.
- * The object being controlled by the OrbitControls (usually the camera) can be accessed via the `controllerObject` property.
+/**
+ * OrbitControls provides interactive camera control using three.js OrbitControls.
+ * Users can rotate, pan, and zoom the camera to explore 3D scenes.
+ *
+ * **Features:**
+ * - Rotation around a target point (orbit)
+ * - Panning to move the view
+ * - Zooming via scroll or pinch
+ * - Auto-rotation for showcases
+ * - Configurable angle and distance limits
+ * - Smooth damping for natural feel
+ *
+ * ![](https://cloud.needle.tools/-/media/ylC34hrC3srwyzGNhFRbEQ.gif)
+ *
+ * **Access underlying controls:**
+ * - `controls` - The three.js OrbitControls instance
+ * - `controllerObject` - The object being controlled (usually the camera)
+ *
+ * **Debug options:**
+ * - `?debugorbit` - Log orbit control events
+ * - `?freecam` - Enable unrestricted camera movement
+ *
+ * @example Basic setup
+ * ```ts
+ * const orbitControls = camera.getComponent(OrbitControls);
+ * orbitControls.autoRotate = true;
+ * orbitControls.autoRotateSpeed = 2;
+ * ```
+ *
+ * @example Set look-at target
+ * ```ts
+ * orbitControls.setLookTargetPosition(new Vector3(0, 1, 0), true);
+ * // Or move both camera and target
+ * orbitControls.setCameraTargetPosition(new Vector3(5, 2, 5), new Vector3(0, 0, 0));
+ * ```
+ *
  * @summary Camera controller using three.js OrbitControls
  * @category Camera and Controls
  * @group Components
+ * @see {@link LookAtConstraint} for setting the look-at target
+ * @see {@link SmoothFollow} for smooth camera following
+ * @see {@link Camera} for camera configuration
+ * @link https://threejs.org/docs/#examples/en/controls/OrbitControls
+ * @link https://engine.needle.tools/samples/panorama-controls alternative controls in samples
  */
 export declare class OrbitControls extends Component implements ICameraController {
     /**
@@ -11304,13 +12556,81 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      declare type OwnershipEventNamesIncoming = Exclude<`${OwnershipEvent}`, "request-has-owner" | "request-is-owner" | "request-ownership" | "remove-ownership">;
 
-     /** Class for abstracting the concept of ownership regarding a networked object or component.
-      * A component that is owned by another user can not be modified through networking (the server will reject changes) */
+     /**
+      * Manages ownership of networked objects or components.
+      *
+      * In multiplayer scenarios, ownership determines which client has authority to modify an object.
+      * The networking server rejects changes from clients that don't own an object. This prevents conflicts
+      * when multiple users try to manipulate the same object simultaneously.
+      *
+      * **Ownership states:**
+      * - `hasOwnership`: This client owns the object and can modify it
+      * - `isOwned`: Some client (could be local or remote) owns the object
+      * - `undefined`: Ownership state is unknown (not yet queried)
+      *
+      * **Typical workflow:**
+      * 1. Request ownership before modifying an object
+      * 2. Make your changes while you have ownership
+      * 3. Free ownership when done (or keep it if still interacting)
+      *
+      * @example Basic usage
+      * ```ts
+      * export class MyComponent extends Behaviour {
+      *   private ownership?: OwnershipModel;
+      *
+      *   awake() {
+      *     this.ownership = new OwnershipModel(this.context.connection, this.guid);
+      *   }
+      *
+      *   onClick() {
+      *     // Request ownership before modifying the object
+      *     this.ownership.requestOwnership();
+      *   }
+      *
+      *   update() {
+      *     if (this.ownership.hasOwnership) {
+      *       // Safe to modify and sync the object
+      *       this.gameObject.position.y += 0.01;
+      *     }
+      *   }
+      *
+      *   onDisable() {
+      *     // Release ownership when done
+      *     this.ownership.freeOwnership();
+      *     this.ownership.destroy();
+      *   }
+      * }
+      * ```
+      *
+      * @example Async ownership
+      * ```ts
+      * async modifyObject() {
+      *   try {
+      *     await this.ownership.requestOwnershipAsync();
+      *     // Now guaranteed to have ownership
+      *     this.transform.position.x = 5;
+      *   } catch(e) {
+      *     console.log("Failed to gain ownership");
+      *   }
+      * }
+      * ```
+      *
+      * @see {@link SyncedTransform} for a complete example of ownership in action
+      * @link https://engine.needle.tools/docs/networking.html
+      */
      export declare class OwnershipModel {
+         /** The unique identifier (GUID) of the object this ownership model manages */
          guid: string;
          private connection;
+         /**
+          * Checks if the local client has ownership of this object.
+          * @returns `true` if this client owns the object and can modify it, `false` otherwise
+          */
          get hasOwnership(): boolean;
-         /** @returns true of anyone has ownership */
+         /**
+          * Checks if anyone (local or remote client) has ownership of this object.
+          * @returns `true` if someone owns the object, `false` if no one owns it, `undefined` if unknown
+          */
          get isOwned(): boolean | undefined;
          /**
           * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `isInRoom` property.
@@ -11324,13 +12644,50 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _hasOwnerResponse;
          constructor(connection: NetworkConnection, guid: string);
          private _isWaitingForOwnershipResponseCallback;
+         /**
+          * Queries the server to update the `isOwned` state.
+          * Call this to check if anyone currently has ownership.
+          */
          updateIsOwned(): void;
          private onHasOwnerResponse;
+         /**
+          * Requests ownership only if the object is not currently owned by anyone.
+          * Internally checks ownership state first, then requests ownership if free.
+          * @returns this OwnershipModel instance for method chaining
+          */
          requestOwnershipIfNotOwned(): OwnershipModel;
          private waitForHasOwnershipRequestResponse;
+         /**
+          * Requests ownership and waits asynchronously until ownership is granted or timeout occurs.
+          * @returns Promise that resolves with this OwnershipModel when ownership is gained
+          * @throws Rejects with "Timeout" if ownership is not gained within ~1 second
+          * @example
+          * ```ts
+          * try {
+          *   await ownership.requestOwnershipAsync();
+          *   // 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
+          */
          requestOwnership(): 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.
+          * @returns this OwnershipModel instance for method chaining
+          */
          freeOwnership(): OwnershipModel;
+         /**
+          * Cleans up event listeners and resources.
+          * Call this when the OwnershipModel is no longer needed (e.g., in `onDestroy()`).
+          */
          destroy(): void;
          private onGainedOwnership;
          private onLostOwnership;
@@ -11412,15 +12769,56 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * The ParticleSystem component efficiently handles the motion and rendering of many individual particles.
+      * ParticleSystem efficiently handles the motion and rendering of many individual particles.
+      * Use it for visual effects like fire, smoke, sparks, rain, magic spells, and more.
+      *
+      * ![](https://cloud.needle.tools/-/media/qz5nO-raa7dNb_XCBNxHmA.gif)
+      * ![](https://cloud.needle.tools/-/media/IKOrLhesy1dKTfQQxx_pLA.gif)
+      *
+      * **Modules:**
+      * Configure particle behavior through modules like {@link EmissionModule}, {@link ShapeModule},
+      * {@link ColorOverLifetimeModule}, {@link SizeOverLifetimeModule}, {@link VelocityOverLifetimeModule},
+      * {@link NoiseModule}, and {@link TrailModule}.
+      *
+      * **Custom behaviors:**
+      * Add custom particle behaviors by extending {@link ParticleSystemBaseBehaviour} and
+      * calling `addBehaviour()`. This gives you full control over particle initialization and updates.
+      *
+      * **Performance:**
+      * Particles are batched together for fast, performant rendering even on low-end devices.
+      * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) internally.
+      *
+      * @example Basic playback control
+      * ```ts
+      * const ps = myObject.getComponent(ParticleSystem);
+      * ps.play();
+      * ps.emit(10); // Emit 10 particles immediately
+      * ps.pause();
+      * ps.stop(true, true); // Stop and clear all particles
+      * ```
       *
-      * You can add custom behaviours to the particle system to fully customize the behaviour of the particles. See {@link ParticleSystemBaseBehaviour} and {@link ParticleSystem.addBehaviour} for more information.
+      * @example Custom particle behavior
+      * ```ts
+      * class GravityBehaviour extends ParticleSystemBaseBehaviour {
+      *   update(particle: Particle, delta: number) {
+      *     particle.velocity.y -= 9.8 * delta;
+      *   }
+      * }
+      * particleSystem.addBehaviour(new GravityBehaviour());
+      * ```
       *
-      * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
+      * - Example: https://engine.needle.tools/samples/particles
+      * - Example: https://engine.needle.tools/samples/particle-bursts
+      * - Example: https://engine.needle.tools/samples/particles-on-collision
       *
       * @summary Handles the motion and rendering of many individual particles
       * @category Rendering
       * @group Components
+      * @see {@link ParticleSystemBaseBehaviour} for custom particle behaviors
+      * @see {@link EmissionModule} for emission configuration
+      * @see {@link ShapeModule} for emission shape control
+      * @see {@link TrailModule} for particle trails
+      * @link https://engine.needle.tools/docs/features/particles.html
       */
      export declare class ParticleSystem extends Component implements IParticleSystem {
          play(includeChildren?: boolean): void;
@@ -11550,16 +12948,45 @@ export declare class OrbitControls extends Component implements ICameraControlle
          SingleRow = 1
      }
 
+     /**
+      * Base class for custom particle behaviors. Extend this to create custom particle logic.
+      *
+      * Override `initialize()` to set up per-particle state when particles spawn.
+      * Override `update()` to modify particles each frame (position, velocity, color, size, etc.).
+      * Override `frameUpdate()` for logic that runs once per frame (not per particle).
+      *
+      * @example Custom wind effect
+      * ```ts
+      * class WindBehaviour extends ParticleSystemBaseBehaviour {
+      *   windStrength = 2;
+      *   windDirection = new Vector3(1, 0, 0);
+      *
+      *   update(particle: Particle, delta: number) {
+      *     particle.velocity.addScaledVector(this.windDirection, this.windStrength * delta);
+      *   }
+      * }
+      * ```
+      *
+      * @see {@link ParticleSystem.addBehaviour} to register your custom behavior
+      * @link https://github.com/Alchemist0823/three.quarks
+      */
      export declare abstract class ParticleSystemBaseBehaviour implements QParticleBehaviour {
+         /** Reference to the particle system this behavior belongs to */
          system: ParticleSystem;
+         /** Access to the engine context for timing, input, etc. */
          get context(): Context;
          constructor(ps?: ParticleSystem);
+         /** Behavior type identifier used by three.quarks */
          type: string;
+         /** Called once when a particle is spawned. Use to initialize per-particle state. */
          initialize(_particle: QParticle): void;
+         /** Called every frame for each active particle. Use to update particle properties. */
          update(_particle: QParticle, _delta: number): void;
+         /** Called once per frame before particle updates. Use for shared calculations. */
          frameUpdate(_delta: number): void;
          toJSON(): void;
          clone(): QParticleBehaviour;
+         /** Called when the particle system is reset. */
          reset(): void;
      }
 
@@ -11712,10 +13139,44 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private trySetupClient;
      }
 
+     /**
+      * Provides physics utilities including raycasting and overlap detection.
+      * Access via `this.context.physics` from any component.
+      *
+      * For physics engine features (rigidbodies, colliders, forces, etc.), use `this.context.physics.engine`.
+      * The physics engine is {@link RapierPhysics}, which uses the Rapier physics library for realistic simulation.
+      *
+      * **Performance - Automatic MeshBVH:**
+      * Needle Engine automatically uses [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh) to accelerate raycasting.
+      * MeshBVH structures are generated automatically on web workers in the background, making raycasts significantly faster
+      * without blocking the main thread. This happens transparently - you don't need to do anything to enable it.
+      * While the BVH is being generated, raycasts fall back to standard three.js raycasting (configurable via `allowSlowRaycastFallback`).
+      *
+      * @example Raycasting from mouse position
+      * ```ts
+      * const hits = this.context.physics.raycast();
+      * if (hits.length > 0) {
+      *   console.log("Hit:", hits[0].object.name);
+      * }
+      * ```
+      * @example Raycasting with inline options
+      * ```ts
+      * const hits = this.context.physics.raycast({
+      *   maxDistance: 100, // Only hit objects within 100 units
+      *   layerMask: 1, // Only layer 0
+      *   ignore: [this.gameObject] // Ignore self
+      * });
+      * ```
+      * @example Physics engine raycast (against colliders only)
+      * ```ts
+      * const hit = this.context.physics.engine?.raycast(origin, direction);
+      * ```
+      * @see {@link RapierPhysics} for physics engine implementation details
+      */
      export declare class Physics {
          private static _raycasting;
          /**
-          * Returns true if raycasting is currently happening
+          * Returns true if raycasting is currently in progress
           */
          static get raycasting(): boolean;
          /**@deprecated use `this.context.physics.engine.raycast` {@link IPhysicsEngine.raycast} */
@@ -11818,44 +13279,115 @@ export declare class OrbitControls extends Component implements ICameraControlle
      };
 
      /**
-      * The PlayableDirector component is the main component to control timelines in needle engine.
-      * It is used to play, pause, stop and evaluate timelines.
-      * Assign a TimelineAsset to the `playableAsset` property to start playing a timeline.
-      * @summary Controls and plays TimelineAssets
-      * @category Animation and Sequencing
-      * @group Components
-      */
-     export declare class PlayableDirector extends Component {
-         private static createTrackFunctions;
-         static registerCreateTrack(type: string, fn: CreateTrackFunction): void;
+      * PlayableDirector is the main component for controlling timelines in Needle Engine.
+      * It orchestrates playback of TimelineAssets containing animation, audio, signal,
+      * control, and activation tracks.
+      *
+      * **Supported track types:**
+      * - Animation tracks - animate objects using AnimationClips
+      * - Audio tracks - play synchronized audio
+      * - Activation tracks - show/hide objects at specific times
+      * - Signal tracks - trigger events at specific points
+      * - Control tracks - control nested timelines or prefab instances
+      * - Marker tracks - add metadata and navigation points
+      *
+      * [![](https://cloud.needle.tools/-/media/HFudFwl8J8D-Kt_VPu7pRw.gif)](https://engine.needle.tools/samples/bike-scrollytelling-responsive-3d)
+      *
+      * [![](https://cloud.needle.tools/-/media/xJ1rI3STbZRnOoWJrSzqlQ.gif)](https://app.songsofcultures.com/?scene=little-brother)
+      *
+      * **Playback control:**
+      * Use `play()`, `pause()`, `stop()` for basic control.
+      * Set `time` directly and call `evaluate()` for scrubbing.
+      * Adjust `speed` for playback rate and `weight` for blending.
+      *
+      * @example Basic timeline playback
+      * ```ts
+      * const director = myObject.getComponent(PlayableDirector);
+      * director.play();
+      * // Jump to specific time
+      * director.time = 2.5;
+      * director.evaluate();
+      * ```
+      *
+      * @example Control playback speed
+      * ```ts
+      * director.speed = 0.5; // Half speed
+      * director.speed = -1;  // Reverse playback
+      * ```
+      *
+      * - Example: https://engine.needle.tools/samples-uploads/product-flyover/
+      *
+      * @summary Controls and plays TimelineAssets
+      * @category Animation and Sequencing
+      * @group Components
+      * @see {@link Animator} for playing individual AnimationClips
+      * @see {@link AudioSource} for standalone audio playback
+      * @see {@link SignalReceiver} for handling timeline signals
+      * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
+      * @link https://app.songsofcultures.com/
+      */
+     export declare class PlayableDirector extends Component {
+         private static createTrackFunctions;
          /**
-          * The timeline asset that is played by this director.
+          * Register a function to create a track handler for a custom track type.
+          * This allows you to extend the timeline system with your own track types and handlers.
+          */
+         static registerCreateTrack(type: string, fn: CreateTrackFunction): void;
+         /**
+          * The timeline asset containing tracks, clips, and markers that this director will play.
+          * Assign a timeline asset exported from Unity or Blender to enable playback.
           */
          playableAsset?: Models.TimelineAssetModel;
-         /** Set to true to start playing the timeline when the scene starts */
+         /**
+          * When true, the timeline starts playing automatically when the component awakens.
+          * Set to false to control playback manually via `play()`.
+          * @default false
+          */
          playOnAwake?: boolean;
          /**
           * Determines how the timeline behaves when it reaches the end of its duration.
           * @default DirectorWrapMode.Loop
           */
          extrapolationMode: DirectorWrapMode;
-         /** @returns true if the timeline is currently playing */
+         /** Returns true if the timeline is currently playing (not paused or stopped). */
          get isPlaying(): boolean;
-         /** @returns true if the timeline is currently paused */
+         /** Returns true if the timeline is currently paused. */
          get isPaused(): boolean;
-         /** the current time of the timeline */
+         /**
+          * The current playback time in seconds. Set this and call `evaluate()` to scrub.
+          * @example Scrub to a specific time
+          * ```ts
+          * director.time = 5.0;
+          * director.evaluate();
+          * ```
+          */
          get time(): number;
          set time(value: number);
-         /** the duration of the timeline */
+         /** The total duration of the timeline in seconds (read from the longest track/clip). */
          get duration(): number;
          set duration(value: number);
-         /** the weight of the timeline. Set to a value below 1 to blend with other timelines */
+         /**
+          * The blend weight of the timeline (0-1). Use values below 1 to blend
+          * timeline animations with other animations like those from an Animator.
+          */
          get weight(): number;
          set weight(value: number);
-         /** the playback speed of the timeline */
+         /**
+          * The playback speed multiplier. Set to negative values for reverse playback.
+          * @example Reverse playback at double speed
+          * ```ts
+          * director.speed = -2;
+          * ```
+          */
          get speed(): number;
          set speed(value: number);
-         /** When enabled the timeline will wait for audio tracks to load at the current time before starting to play */
+         /**
+          * When true, `play()` will wait for audio tracks to load and for user interaction
+          * before starting playback. Web browsers require user interaction (click/tap) before
+          * allowing audio to play - this ensures audio is synchronized with the timeline.
+          * Set to false if you need immediate visual playback and can tolerate audio delay.
+          * @default true
+          */
          waitForAudio: boolean;
          private _visibilityChangeEvt?;
          private _clonedPlayableAsset;
@@ -12211,6 +13743,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          removePlayerView(id: string, device: ViewDevice): void;
      }
 
+     /**
+      * Options for controlling animation playback via {@link Animation.play}.
+      * All options are optional - defaults are sensible for most use cases.
+      *
+      * @see {@link Animation} for the component that uses these options
+      */
      declare type PlayOptions = {
          /**
           * The fade duration in seconds for the action to fade in and other actions to fade out (if exclusive is enabled)
@@ -12340,10 +13878,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /** e.g. `pointerdown` */
      declare type PointerEventNames = EnumToPrimitiveUnion<PointerEnumType>;
 
+     /**
+      * Types of pointer input devices supported by Needle Engine.
+      */
      export declare const enum PointerType {
+         /** Mouse or trackpad input */
          Mouse = "mouse",
+         /** Touch screen input */
          Touch = "touch",
+         /** XR controller input (e.g., VR controllers) */
          Controller = "controller",
+         /** XR hand tracking input */
          Hand = "hand"
      }
 
@@ -12700,6 +14245,82 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      export declare function randomNumber(min: number, max: number): number;
 
+     /**
+      * Rapier physics engine implementation for Needle Engine.
+      *
+      * Rapier is a fast, cross-platform physics engine that provides realistic physics simulation
+      * for rigidbodies, colliders, joints, and collision detection. It runs entirely in WebAssembly
+      * for high performance.
+      *
+      * **Features:**
+      * - Rigidbody simulation (dynamic, kinematic, static)
+      * - Multiple collider shapes (box, sphere, capsule, mesh, convex hull)
+      * - Raycasting and shape overlap queries against physics colliders
+      * - Collision and trigger events
+      * - Joints (fixed, hinge, etc.)
+      * - Continuous collision detection (CCD)
+      * - Physics materials (friction, bounciness)
+      *
+      * **Access:**
+      * The Rapier physics engine is accessible via `this.context.physics.engine` from any component.
+      * Rapier is automatically initialized when physics components are used.
+      *
+      * **Using the Rapier Module Directly:**
+      * Rapier is lazy-loaded for performance. You can access the raw Rapier module via {@link MODULES.RAPIER_PHYSICS}.
+      * Use `MODULES.RAPIER_PHYSICS.load()` to load the module, or `MODULES.RAPIER_PHYSICS.ready()` to wait for it without triggering a load.
+      * Once loaded, the module is available at `MODULES.RAPIER_PHYSICS.MODULE`.
+      *
+      * **Note:**
+      * This is the low-level physics engine implementation. For general raycasting (against all scene objects),
+      * use {@link Physics.raycast} instead. Use this class for physics-specific operations like applying forces,
+      * raycasting against colliders only, or accessing the Rapier world directly.
+      *
+      * @example Applying forces to a rigidbody
+      * ```ts
+      * const rb = this.gameObject.getComponent(Rigidbody);
+      * if (rb) {
+      *   this.context.physics.engine?.addForce(rb, { x: 0, y: 10, z: 0 }, true);
+      * }
+      * ```
+      * @example Raycasting against physics colliders only
+      * ```ts
+      * const origin = { x: 0, y: 5, z: 0 };
+      * const direction = { x: 0, y: -1, z: 0 };
+      * const hit = this.context.physics.engine?.raycast(origin, direction);
+      * if (hit) {
+      *   console.log("Hit collider:", hit.collider.name);
+      * }
+      * ```
+      * @example Accessing Rapier world directly
+      * ```ts
+      * const rapierWorld = this.context.physics.engine?.world;
+      * if (rapierWorld) {
+      *   // Direct access to Rapier API
+      *   console.log("Gravity:", rapierWorld.gravity);
+      * }
+      * ```
+      * @example Using the Rapier module directly
+      * ```ts
+      * import { MODULES } from "@needle-tools/engine";
+      *
+      * // Load the Rapier module
+      * const RAPIER = await MODULES.RAPIER_PHYSICS.load();
+      *
+      * // Now you can use Rapier types and create custom physics objects
+      * const rigidBodyDesc = RAPIER.RigidBodyDesc.dynamic()
+      *   .setTranslation(0, 10, 0);
+      *
+      * // Or access the already-loaded module
+      * if (MODULES.RAPIER_PHYSICS.MODULE) {
+      *   const colliderDesc = MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.ball(1.0);
+      * }
+      * ```
+      * @see {@link Physics} for general raycasting and physics utilities
+      * @see {@link MODULES.RAPIER_PHYSICS} for direct access to the Rapier module
+      * @link https://rapier.rs/docs/ for Rapier documentation
+      * @link https://engine.needle.tools/docs/reference/components.html#physics
+      * @link https://engine.needle.tools/docs/how-to-guides/scripting/use-physics.html
+      */
      export declare class RapierPhysics implements IPhysicsEngine {
          debugRenderColliders: boolean;
          debugRenderRaycasts: boolean;
@@ -12873,9 +14494,21 @@ export declare class OrbitControls extends Component implements ICameraControlle
          protected onAfterCreated(): void;
      }
 
-     /** Derive from this class to create your own custom Raycaster
-      * If you override awake, onEnable or onDisable, be sure to call the base class methods
-      * Implement `performRaycast` to perform your custom raycasting logic
+     /**
+      * Base class for raycasters that detect pointer interactions.
+      * Derive from this class to create custom raycasting logic.
+      *
+      * **Built-in raycasters:**
+      * - {@link ObjectRaycaster} - Raycasts against 3D objects
+      * - {@link GraphicRaycaster} - Raycasts against UI elements
+      * - {@link SpatialGrabRaycaster} - Sphere overlap for XR grab
+      *
+      * **Important:** If you override `awake`, `onEnable`, or `onDisable`,
+      * call the base class methods to ensure proper registration with {@link EventSystem}.
+      *
+      * @category Interactivity
+      * @group Components
+      * @see {@link EventSystem} for the event dispatch system
       */
      declare abstract class Raycaster_2 extends Component {
          awake(): void;
@@ -12979,13 +14612,28 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * A ReflectionProbe provides reflection data to materials within its defined area.
+      * ReflectionProbe provides environment reflection data to materials within its defined area.
+      * Use for chrome-like materials that need accurate environment reflections.
+      *
+      * **Setup:**
+      * 1. Add ReflectionProbe component to an object
+      * 2. Assign a cubemap or HDR texture
+      * 3. In Renderer components, assign the probe as anchor override
       *
-      * - Sample: http://samples.needle.tools/reflection-probes
+      * **Note:** Volume-based automatic assignment is not fully supported yet.
+      * Objects (Renderer components) can explicitly reference their reflection probe.
+      *
+      * **Debug options:**
+      * - `?debugreflectionprobe` - Log probe info
+      * - `?noreflectionprobe` - Disable all reflection probes
+      *
+      * - Example: https://engine.needle.tools/samples/reflection-probes
       *
       * @summary Provides reflection data to materials
       * @category Rendering
       * @group Components
+      * @see {@link Renderer} for material and rendering control
+      * @see {@link Light} for scene lighting
       */
      export declare class ReflectionProbe extends Component {
          private static _probes;
@@ -13171,8 +14819,42 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare function removePatch(prototype: object, fieldName: string, prefixOrPostfix: Prefix | Postfix): void;
 
      /**
+      * Renderer controls rendering properties of meshes including materials,
+      * lightmaps, reflection probes, and GPU instancing.
+      *
+      * **Materials:**
+      * Access materials via `sharedMaterials` array. Changes affect all instances.
+      * Use material cloning for per-instance variations.
+      *
+      * **Instancing:**
+      * Enable GPU instancing for improved performance with many identical objects.
+      * Use `Renderer.setInstanced(obj, true)` or `enableInstancing` property.
+      *
+      * **Lightmaps:**
+      * Baked lighting is automatically applied when exported from Unity.
+      * Access via the associated {@link RendererLightmap} component.
+      *
+      * **Debug options:**
+      * - `?debugrenderer` - Log renderer info
+      * - `?wireframe` - Show wireframe rendering
+      * - `?noinstancing` - Disable GPU instancing
+      *
+      * @example Change material at runtime
+      * ```ts
+      * const renderer = myObject.getComponent(Renderer);
+      * renderer.sharedMaterials[0] = newMaterial;
+      * ```
+      *
+      * @example Enable instancing
+      * ```ts
+      * Renderer.setInstanced(myObject, true);
+      * ```
+      *
       * @category Rendering
       * @group Components
+      * @see {@link ReflectionProbe} for environment reflections
+      * @see {@link Light} for scene lighting
+      * @see {@link LODGroup} for level of detail
       */
      export declare class Renderer extends Component implements IRenderer {
          /** Enable or disable instancing for an object. This will create a Renderer component if it does not exist yet.
@@ -13706,6 +15388,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * - [Needle Website](https://needle.tools)
       * - [Songs Of Cultures](https://app.songsofcultures.com)
       *
+      * ![](https://cloud.needle.tools/-/media/I-atrBcwIcg2kfvPl8c71A.gif)
+      * *Replace entire scenes with the SceneSwitcher.*
+      *
+      * ![](https://cloud.needle.tools/-/media/_FbH-7pkDmluTdfphXlP-A.gif)
+      * *Multiple SceneSwitcher components can be used at the same time and they can also be nested
+      * (a scene loaded by a SceneSwitcher can also have a SceneSwitcher to load sub-scenes).*
+      *
       * ### Interfaces
       * Use the {@link ISceneEventListener} interface to listen to scene open and closing events with the ability to modify transitions and stall the scene loading process.
       *
@@ -13733,6 +15422,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @summary Dynamically loads and switches between multiple scenes
       * @category Asset Management
       * @group Components
+      * @see {@link ISceneEventListener} for scene transition callbacks
+      * @see {@link AssetReference} for loading individual assets
+      * @see {@link NestedGltf} for embedding static glTF content
+      * @link https://engine.needle.tools/docs/how-to-guides/components/scene-switcher.html
       */
      export declare class SceneSwitcher extends Component {
          /** When enabled the first scene will be loaded when the SceneSwitcher becomes active
@@ -13933,17 +15626,49 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * The ScreenCapture component allows you to share your screen, camera or microphone with other users in the networked room.
-      * When the stream is active the video will be displayed on the VideoPlayer component attached to the same GameObject.
+      * ScreenCapture enables sharing screen, camera, or microphone with users in a networked room.
+      * The stream is displayed via a {@link VideoPlayer} component on the same GameObject.
       *
-      * Note: For debugging append `?debugscreensharing` to the URL to see more information in the console.
+      * **Supported capture devices:**
+      * - `Screen` - Share desktop/window/tab
+      * - `Camera` - Share webcam feed
+      * - `Microphone` - Audio only
+      * - `Canvas` - Share the 3D canvas (experimental)
       *
-      * By default the component will start sharing the screen when the user clicks on the object this component is attached to. You can set {@link device} This behaviour can be disabled by setting `allowStartOnClick` to false.
-      * It is also possible to start the stream manually from your code by calling the {@link share} method.
+      * ![](https://cloud.needle.tools/-/media/Ugw6sKj3KNeLMzl0yKQXig.gif)
+      *
+      * **How it works:**
+      * - Click the object to start/stop sharing (if `allowStartOnClick` is true)
+      * - Or call `share()` / `close()` programmatically
+      * - Stream is sent to all users in the same room via WebRTC
+      * - Receiving clients see the video on their VideoPlayer
+      *
+      * **Debug:** Append `?debugscreensharing` to the URL for console logging.
+      *
+      * @example Start screen sharing programmatically
+      * ```ts
+      * const capture = myScreen.getComponent(ScreenCapture);
+      * await capture?.share({ device: "Screen" });
+      *
+      * // Later, stop sharing
+      * capture?.close();
+      * ```
+      *
+      * @example Share webcam with constraints
+      * ```ts
+      * await capture?.share({
+      *   device: "Camera",
+      *   constraints: { width: 1280, height: 720 }
+      * });
+      * ```
       *
       * @summary Share screen, camera or microphone in a networked room
       * @category Networking
       * @group Components
+      * @see {@link VideoPlayer} for displaying the received stream
+      * @see {@link Voip} for voice-only communication
+      * @see {@link SyncedRoom} for room management
+      * @link https://engine.needle.tools/docs/networking.html
       */
      export declare class ScreenCapture extends Component implements IPointerClickHandler {
          /**
@@ -14490,8 +16215,34 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * The serializable attribute should be used to annotate all serialized fields / fields and members that should be serialized and exposed in an editor
-      * @param type The type of the field. If not provided the type will be inferred from the constructor of the field. If the field is a primitive type (string, number, boolean) the type should be null.
+      * Marks a field for serialization and editor exposure. Required for fields that reference
+      * other objects, components, or assets. Primitive types (string, number, boolean) work without a type argument.
+      *
+      * @param type The constructor type for complex objects. Omit for primitives.
+      *
+      * @example Primitive types (no type needed)
+      * ```ts
+      * @serializable()
+      * speed: number = 1;
+      *
+      * @serializable()
+      * label: string = "Hello";
+      * ```
+      * @example Object references
+      * ```ts
+      * @serializable(Object3D)
+      * target: Object3D | null = null;
+      *
+      * @serializable(Renderer)
+      * myRenderer: Renderer | null = null;
+      * ```
+      * @example Arrays
+      * ```ts
+      * @serializable([Object3D])
+      * waypoints: Object3D[] = [];
+      * ```
+      * @see {@link syncField} for automatic network synchronization
+      * @link https://engine.needle.tools/docs/reference/typescript-decorators.html#serializable
       */
      export declare const serializable: <T>(type?: Constructor<T> | TypeResolver<T> | (Constructor<any> | TypeResolver<T>)[] | null | undefined) => (_target: any, _propertyKey: string | {
          name: string;
@@ -14915,11 +16666,54 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare function slerp(vec: Vector3, end: Vector3, t: number): Vector3;
 
      /**
-      * SmoothFollow makes the {@link Object3D} (`GameObject`) smoothly follow another target {@link Object3D}.
-      * It can follow the target's position, rotation, or both.
-      * @summary Smoothly follows a target object
+      * SmoothFollow makes this GameObject smoothly follow another target object's position and/or rotation.
+      *
+      * **Position Following:**
+      * When enabled (`followFactor > 0`), this object will move towards the target's world position.
+      * The object interpolates from its current position to the target's position each frame.
+      * Use `positionAxes` to restrict following to specific axes (e.g., only horizontal movement).
+      *
+      * **Rotation Following:**
+      * When enabled (`rotateFactor > 0`), this object will rotate to match the target's world rotation.
+      * The object smoothly interpolates from its current rotation to the target's rotation each frame.
+      * This makes the object face the same direction as the target, not look at it (use {@link LookAt} for that).
+      *
+      * **Smoothing:**
+      * Both position and rotation use time-based interpolation (lerp/slerp).
+      * Higher factor values = faster following (less lag), lower values = slower following (more lag).
+      * Set a factor to 0 to disable that type of following entirely.
+      *
+      * **Common Use Cases:**
+      * - Camera following a player character
+      * - UI elements tracking world objects
+      * - Delayed motion effects (ghost trails, spring arms)
+      * - Smoothed object attachment
+      *
+      * @example Follow a target with smooth position
+      * ```ts
+      * const follower = myObject.addComponent(SmoothFollow);
+      * follower.target = playerObject;
+      * follower.followFactor = 5;  // Higher = faster following
+      * follower.rotateFactor = 0;  // Don't follow rotation
+      * ```
+      *
+      * @example Follow only on horizontal plane
+      * ```ts
+      * follower.positionAxes = Axes.X | Axes.Z; // Follow X and Z only (no vertical)
+      * ```
+      *
+      * @example Follow both position and rotation
+      * ```ts
+      * follower.target = targetObject;
+      * follower.followFactor = 3;  // Smooth position following
+      * follower.rotateFactor = 2;  // Smooth rotation following
+      * ```
+      *
+      * @summary Smoothly follows a target object's position and/or rotation
       * @category Interactivity
       * @group Components
+      * @see {@link LookAtConstraint} for making an object look at a target (different from rotation following)
+      * @see {@link Mathf} for the interpolation used
       */
      export declare class SmoothFollow extends Component {
          /**
@@ -14927,16 +16721,28 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          target: Object3D | null;
          /**
-          * The factor to smoothly follow the target's position.
-          * The value is clamped between 0 and 1. If 0, the GameObject will not follow the target's position.
+          * Speed factor for position following.
+          * Controls how quickly this object moves to match the target's position.
+          * Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
+          * Set to 0 to disable position following entirely.
+          * @default 0.1
           */
          followFactor: number;
          /**
-          * The factor to smoothly follow the target's rotation.
-          * The value is clamped between 0 and 1. If 0, the GameObject will not follow the target's rotation.
+          * Speed factor for rotation following.
+          * Controls how quickly this object rotates to match the target's rotation.
+          * Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
+          * Set to 0 to disable rotation following entirely.
+          * @default 0.1
           */
          rotateFactor: number;
+         /**
+          * Which position axes to follow. Use bitwise OR to combine:
+          * `Axes.X | Axes.Y` follows only X and Y axes.
+          * @default Axes.All
+          */
          positionAxes: Axes;
+         /** When true, rotates 180° around Y axis (useful for mirrored setups) */
          flipForward: boolean;
          private static _invertForward;
          private _firstUpdate;
@@ -14944,6 +16750,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * Update the position and rotation of the GameObject to follow the target.
           */
          onBeforeRender(): void;
+         /**
+          * Manually update the position/rotation to follow the target.
+          * @param hard If true, snaps instantly to target without smoothing
+          */
          updateNow(hard: boolean): void;
      }
 
@@ -14953,10 +16763,19 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /* Excluded from this release type: Space */
 
      /**
-      * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.
+      * SpatialGrabRaycaster enables direct grab interactions in VR/AR.
+      * Uses sphere overlap detection around the controller/hand position
+      * to allow grabbing objects by reaching into them.
+      *
+      * **Features:**
+      * - Active only during XR sessions
+      * - Can be globally disabled via `SpatialGrabRaycaster.allow`
+      * - Works alongside ray-based interaction
       *
       * @category XR
       * @group Components
+      * @see {@link WebXR} for XR session management
+      * @see {@link DragControls} for object manipulation
       */
      export declare class SpatialGrabRaycaster extends Raycaster_2 {
          /**
@@ -14983,9 +16802,33 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * A spatial trigger component that detects objects within a box-shaped area.
-      * Used to trigger events when objects enter, stay in, or exit the defined area
+      * Used to trigger events when objects enter, stay in, or exit the defined area.
+      *
+      * The trigger area is defined by the GameObject's bounding box (uses {@link BoxHelperComponent}).
+      * Objects with {@link SpatialTriggerReceiver} components are tested against this area.
+      *
+      * **Mask system:** Both trigger and receiver have a `triggerMask` - they only interact
+      * when their masks have overlapping bits set. This allows selective triggering.
+      *
+      * **Debug:** Use `?debugspatialtrigger` URL parameter to visualize trigger zones.
+      *
+      * @example Create a pickup zone
+      * ```ts
+      * // On the pickup zone object
+      * const trigger = pickupZone.addComponent(SpatialTrigger);
+      * trigger.triggerMask = 1; // Layer 1 for pickups
+      *
+      * // On the player
+      * const receiver = player.addComponent(SpatialTriggerReceiver);
+      * receiver.triggerMask = 1; // Match the pickup layer
+      * ```
+      *
+      * @summary Define a trigger zone that detects entering objects
       * @category Interactivity
       * @group Components
+      * @see {@link SpatialTriggerReceiver} for objects that respond to triggers
+      * @see {@link BoxHelperComponent} for the underlying box used to define the trigger area
+      * @link https://engine.needle.tools/samples/spatial-triggers/
       */
      export declare class SpatialTrigger extends Component {
          /** Global registry of all active spatial triggers in the scene */
@@ -15035,9 +16878,32 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * Component that receives and responds to spatial events, like entering or exiting a trigger zone.
       * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.
+      *
+      * Place this on objects that should react when entering trigger zones. The receiver checks
+      * against all active SpatialTriggers each frame and fires events when intersections change.
+      *
+      * Events can be connected via {@link EventList} in the editor or listened to in code.
+      *
+      * @example Listen to trigger events
+      * ```ts
+      * export class DoorTrigger extends Behaviour {
+      *   @serializable(SpatialTriggerReceiver)
+      *   receiver?: SpatialTriggerReceiver;
+      *
+      *   start() {
+      *     this.receiver?.onEnter?.addEventListener(() => {
+      *       console.log("Player entered door zone");
+      *     });
+      *   }
+      * }
+      * ```
+      *
       * @summary Receives spatial trigger events
       * @category Interactivity
       * @group Components
+      * @see {@link SpatialTrigger} for defining trigger zones
+      * @see {@link EventList} for event handling
+      * @link https://engine.needle.tools/samples/spatial-triggers/
       */
      export declare class SpatialTriggerReceiver extends Component {
          /**
@@ -15075,14 +16941,32 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Provides functionality to follow and spectate other users in a networked environment.
-      * Handles camera switching, following behavior, and network synchronization for spectator mode.
+      * SpectatorCamera enables following and spectating other users in networked sessions.
+      * Switch between first-person (see what they see) and third-person (orbit around them) views.
+      *
+      * **Keyboard controls** (when `useKeys = true`):
+      * - `F` - Request all users to follow the local player
+      * - `ESC` - Stop spectating
+      *
+      * **Spectator modes:**
+      * - `FirstPerson` - View from the followed player's perspective
+      * - `ThirdPerson` - Freely orbit around the followed player
       *
-      * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
+      * **Debug:** Use `?debugspectator` URL parameter for logging.
+      *
+      * @example Start spectating a user
+      * ```ts
+      * const spectator = camera.getComponent(SpectatorCamera);
+      * spectator.follow(targetUserId);
+      * spectator.mode = SpectatorMode.ThirdPerson;
+      * ```
       *
       * @summary Spectator camera for following other users
       * @category Networking
       * @group Components
+      * @see {@link SpectatorMode} for view options
+      * @see {@link SyncedRoom} for networked sessions
+      * @see {@link OrbitControls} for third-person orbit
       */
      export declare class SpectatorCamera extends Component {
          /** Reference to the Camera component on this GameObject */
@@ -15187,14 +17071,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * SphereCollider represents a sphere-shaped collision volume.
-      * Useful for objects that are roughly spherical in shape or need a simple collision boundary.
+      * Efficient and suitable for balls, projectiles, or approximate collision bounds.
+      *
+      * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+      *
+      * @example Create a bouncing ball
+      * ```ts
+      * const sphere = ball.addComponent(SphereCollider);
+      * sphere.radius = 0.5;
+      * const rb = ball.addComponent(Rigidbody);
+      * rb.mass = 1;
+      * ```
       *
       * - Example: https://samples.needle.tools/physics-basic
-      * - Example: https://samples.needle.tools/physics-playground
-      * - Example: https://samples.needle.tools/physics-&-animation
       *
+      * @summary Sphere-shaped physics collider
       * @category Physics
       * @group Components
+      * @see {@link Collider} for base collider functionality
+      * @see {@link CapsuleCollider} for elongated sphere shapes
       */
      export declare class SphereCollider extends Collider implements ISphereCollider {
          /**
@@ -15587,11 +17482,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /* Excluded from this release type: SubEmitterSystem */
 
+     /**
+      * Defines when a sub-emitter spawns particles relative to the parent particle's lifecycle.
+      * Used to create complex effects like explosions on impact or trails following particles.
+      */
      declare enum SubEmitterType {
+         /** Sub-emitter triggers when the parent particle is born */
          Birth = 0,
+         /** Sub-emitter triggers when the parent particle collides */
          Collision = 1,
+         /** Sub-emitter triggers when the parent particle dies */
          Death = 2,
+         /** Sub-emitter triggers when the parent particle enters a trigger zone */
          Trigger = 3,
+         /** Sub-emitter is triggered manually via code */
          Manual = 4
      }
 
@@ -15664,9 +17568,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * myObject.addComponent(SyncedRoom, { joinRandomRoom: true, roomPrefix: "myApp_" });
       * ```
       *
+      * **Debug:** Use `?debugsyncedroom` URL parameter for logging.
+      *
       * @summary Joins a networked room based on URL parameters or a random room
       * @category Networking
       * @group Components
+      * @see {@link SyncedTransform} for synchronizing object transforms
+      * @see {@link Voip} for voice communication in rooms
+      * @see {@link ScreenCapture} for screen/video sharing
+      * @link https://engine.needle.tools/docs/networking.html
       */
      export declare class SyncedRoom extends Component {
          /**
@@ -15744,12 +17654,48 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * SyncedTransform synchronizes the position and rotation of a game object over the network.
-      * It handles ownership transfer, interpolation, and network state updates automatically.
+      * SyncedTransform synchronizes position and rotation of a GameObject across the network.
+      * When users interact with an object (e.g., via {@link DragControls}), they automatically
+      * take ownership and their changes are broadcast to other users.
+      *
+      * **Features:**
+      * - Automatic ownership transfer when interacting
+      * - Smooth interpolation of remote updates
+      * - Physics integration (can override kinematic state)
+      * - Fast mode for rapidly moving objects
+      *
+      * **Requirements:**
+      * - Active network connection via {@link SyncedRoom}
+      * - Objects must have unique GUIDs (set automatically in Unity/Blender export)
+      *
+      * **Ownership:**
+      * This component uses {@link OwnershipModel} internally to manage object ownership.
+      * Only the client that owns an object can send transform updates. Use `requestOwnership()`
+      * before modifying the transform, or check `hasOwnership()` to see if you can modify it.
+      *
+      * **Debug:** Use `?debugsync` URL parameter for logging.
+      *
+      * @example Basic networked object
+      * ```ts
+      * // Add to any object you want synced
+      * const sync = myObject.addComponent(SyncedTransform);
+      * sync.fastMode = true; // For fast-moving objects
+      *
+      * // Request ownership before modifying
+      * sync.requestOwnership();
+      * myObject.position.x += 1;
+      * ```
+      *
+      * - Example: https://engine.needle.tools/samples/collaborative-sandbox
       *
       * @summary Synchronizes object transform over the network with ownership management
       * @category Networking
       * @group Components
+      * @see {@link SyncedRoom} for room/session management
+      * @see {@link OwnershipModel} for ownership management details
+      * @see {@link DragControls} for interactive dragging with sync
+      * @see {@link Duplicatable} for networked object spawning
+      * @link https://engine.needle.tools/docs/networking.html
       */
      export declare class SyncedTransform extends Component {
          /** When true, overrides physics behavior when this object is owned by the local user */
@@ -15774,22 +17720,35 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /**
           * Requests ownership of this object on the network.
           * You need to be connected to a room for this to work.
+          * Call this before modifying the object's transform to ensure your changes are synchronized.
+          *
+          * @example
+          * ```ts
+          * // Request ownership before modifying
+          * syncedTransform.requestOwnership();
+          * this.gameObject.position.y += 1;
+          * ```
+          * @see {@link OwnershipModel.requestOwnership} for more details
           */
          requestOwnership(): void;
          /**
           * Free ownership of this object on the network.
           * You need to be connected to a room for this to work.
           * This will also be called automatically when the component is disabled.
+          * Call this when you're done modifying an object to allow other users to interact with it.
+          * @see {@link OwnershipModel.freeOwnership} for more details
           */
          freeOwnership(): void;
          /**
-          * Checks if this client has ownership of the object
-          * @returns true if this client has ownership, false if not, undefined if ownership state is unknown
+          * Checks if this client has ownership of the object.
+          * @returns `true` if this client has ownership, `false` if not, `undefined` if ownership state is unknown
+          * @see {@link OwnershipModel.hasOwnership} for more details
           */
          hasOwnership(): boolean | undefined;
          /**
-          * Checks if the object is owned by any client
-          * @returns true if the object is owned, false if not, undefined if ownership state is unknown
+          * Checks if the object is owned by any client (local or remote).
+          * @returns `true` if the object is owned, `false` if not, `undefined` if ownership state is unknown
+          * @see {@link OwnershipModel.isOwned} for more details
           */
          isOwned(): boolean | undefined;
          private joinedRoomCallback;
@@ -15816,15 +17775,42 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * **Decorate a field to be automatically networked synced**
-      * *Primitive* values are all automatically synced (like string, boolean, number).
-      * For *arrays or objects* make sure to re-assign them (e.g. `this.mySyncField = this.mySyncField`) to trigger an update
+      * Marks a field for automatic network synchronization across connected clients.
+      * When a synced field changes, the new value is automatically broadcast to all users in the room.
+      *
+      * Primitives (string, number, boolean) sync automatically.
+      * For arrays/objects, reassign to trigger sync: `this.myArray = this.myArray`
+      *
+      * @param onFieldChanged Optional callback when the field changes (locally or from network).
+      * Return `false` to prevent syncing this change to others.
       *
-      * @param onFieldChanged name of a callback function that will be called when the field is changed.
-      * You can also pass in a function like so: syncField(myClass.prototype.myFunctionToBeCalled)
-      * Note: if you return `false` from this function you'll prevent the field from being synced with other clients
-      * (for example a networked color is sent as a number and may be converted to a color in the receiver again)
-      * Parameters: (newValue, previousValue)
+      * @example Basic sync
+      * ```ts
+      * class MyComponent extends Behaviour {
+      *   @syncField() playerScore: number = 0;
+      * }
+      * ```
+      * @example With change callback
+      * ```ts
+      * class MyComponent extends Behaviour {
+      *   @syncField("onHealthChanged") health: number = 100;
+      *
+      *   onHealthChanged(newValue: number, oldValue: number) {
+      *     console.log(`Health: ${oldValue} → ${newValue}`);
+      *   }
+      * }
+      * ```
+      * @example Preventing sync (one-way)
+      * ```ts
+      * class MyComponent extends Behaviour {
+      *   @syncField(function(newVal, oldVal) {
+      *     // Process incoming value but don't sync our changes
+      *     return false;
+      *   }) serverControlled: string = "";
+      * }
+      * ```
+      * @see {@link serializable} for editor serialization
+      * @link https://engine.needle.tools/docs/how-to-guides/networking/
       */
      export declare const syncField: (onFieldChanged?: string | FieldChangedCallbackFn | undefined | null) => (target: any, _propertyKey: string | {
          name: string;
@@ -15853,11 +17839,30 @@ export declare class OrbitControls extends Component implements ICameraControlle
      declare type Target = USDObject | USDObject[] | Object3D | Object3D[];
 
      /**
-      * This component is just used as a marker on objects for WebXR teleportation
-      * The {@link XRControllerMovement} component can be configured to check if the TeleportTarget component is present on an object to allow teleporting to that object.
+      * Marks a GameObject as a valid teleportation target for VR locomotion.
+      * Add this component to objects or surfaces where users should be able to teleport.
+      *
+      * **Usage:**
+      * - Add to floor surfaces, platforms, or designated teleport spots
+      * - Works with {@link XRControllerMovement} component's teleport system
+      * - Can be used to restrict teleportation to specific areas
+      *
+      * **Setup:**
+      * 1. Add this component to GameObjects that should be teleport destinations
+      * 2. Configure {@link XRControllerMovement} to use teleport targets (optional)
+      * 3. Test teleportation in VR mode
+      *
+      * @example
+      * ```ts
+      * // Make a platform teleportable
+      * const platform = myPlatform.addComponent(TeleportTarget);
+      * ```
       *
+      * @summary Marker component for valid VR teleportation destinations
       * @category XR
       * @group Components
+      * @see {@link XRControllerMovement} for VR locomotion and teleport configuration
+      * @see {@link WebXR} for general WebXR setup
       */
      export declare class TeleportTarget extends Component {
      }
@@ -15891,11 +17896,33 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /* Excluded from this release type: TestSimulateUserData */
 
      /**
-      * Text is a UI component that displays text in the user interface.
+      * Text displays text content in the UI. Supports custom fonts, colors,
+      * alignment, and basic rich text formatting.
+      *
+      * **Text properties:**
+      * - `text` - The string content to display
+      * - `fontSize` - Size of the text in pixels
+      * - `color` - Text color (inherited from Graphic)
+      * - `alignment` - Text anchor position (UpperLeft, MiddleCenter, etc.)
+      *
+      * **Fonts:**
+      * Set the `font` property to a URL pointing to a font file.
+      * Supports MSDF (Multi-channel Signed Distance Field) fonts for crisp rendering.
+      *
+      * @example Update text at runtime
+      * ```ts
+      * const text = myLabel.getComponent(Text);
+      * text.text = "Score: " + score;
+      * text.fontSize = 24;
+      * text.color = new RGBAColor(1, 1, 1, 1);
+      * ```
       *
       * @summary Display text in the UI
       * @category User Interface
       * @group Components
+      * @see {@link Canvas} for the UI root
+      * @see {@link TextAnchor} for alignment options
+      * @see {@link FontStyle} for bold/italic styles
       */
      declare class Text_2 extends Graphic implements IHasAlphaFactor, ICanvasEventReceiver {
          alignment: TextAnchor_2;
@@ -16068,8 +18095,23 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Time is a class that provides time-related information.
-      * It is created and used within the Needle Engine Context.
+      * Provides time-related information for frame-based game logic.
+      * Access via `this.context.time` from any component.
+      *
+      * @example Using deltaTime for frame-rate independent movement
+      * ```ts
+      * update() {
+      *   // Move 1 unit per second regardless of frame rate
+      *   this.gameObject.position.x += 1 * this.context.time.deltaTime;
+      * }
+      * ```
+      * @example Checking elapsed time
+      * ```ts
+      * start() {
+      *   console.log(`Time since start: ${this.context.time.time}s`);
+      *   console.log(`Current frame: ${this.context.time.frameCount}`);
+      * }
+      * ```
       */
      export declare class Time implements ITime {
          /** The time in seconds since the start of Needle Engine. */
@@ -16083,7 +18125,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /** The time in seconds it took to complete the last frame (Read Only). Timescale is not applied. */
          get deltaTimeUnscaled(): number;
          private _deltaTimeUnscaled;
-         /** The scale at which time passes. This can be used for slow motion effects or to speed up time. */
+         /**
+          * The scale at which time passes. Default is 1.
+          * - Values < 1 create slow motion (e.g. 0.5 = half speed)
+          * - Values > 1 speed up time (e.g. 2 = double speed)
+          * - Value of 0 effectively pauses time-dependent logic
+          */
          timeScale: number;
          /** same as frameCount */
          get frame(): number;
@@ -16280,12 +18327,39 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
-      * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
+      * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects.
+      * Wraps three.js {@link TransformControls} with keyboard shortcuts and snapping support.
+      *
+      * **Keyboard shortcuts:**
+      * - `W` - Translate mode
+      * - `E` - Rotate mode
+      * - `R` - Scale mode
+      * - `Q` - Toggle local/world space
+      * - `Shift` (hold) - Enable grid snapping
+      * - `+/-` - Adjust gizmo size
+      * - `X/Y/Z` - Toggle axis visibility
+      * - `Space` - Toggle controls enabled
+      *
+      * **Snapping:**
+      * Configure grid snapping with `translationSnap`, `rotationSnapAngle`, and `scaleSnap`.
       *
-      * @summary Object manipulation gizmo for translating, rotating, and scaling
+      * **Networking:**
+      * Automatically works with {@link SyncedTransform} for multiplayer editing.
+      *
+      * @example Add transform gizmo to an object
+      * ```ts
+      * const gizmo = editableObject.addComponent(TransformGizmo);
+      * gizmo.translationSnap = 0.5; // Snap to 0.5 unit grid
+      * gizmo.rotationSnapAngle = 45; // Snap to 45° increments
+      * ```
+      *
+      * @summary Object manipulation gizmo for translate/rotate/scale
       * @category Helpers
       * @group Components
+      * @see {@link DragControls} for simpler drag-only interaction
+      * @see {@link SyncedTransform} for network synchronization
+      * @see {@link OrbitControls} - automatically disabled during gizmo drag
+      * @link https://threejs.org/docs/index.html#examples/en/controls/TransformControls for underlying three.js controls and additional features
       */
      export declare class TransformGizmo extends Component {
          /**
@@ -16504,8 +18578,23 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Marks an object as currently being interacted with.
-      * For example, DragControls set this on the dragged object to prevent DeleteBox from deleting it.
+      * UsageMarker indicates an object is currently being interacted with.
+      * Components like {@link DragControls} add this to prevent accidental deletion
+      * by {@link DeleteBox} while the user is dragging.
+      *
+      * @example Check if object is in use
+      * ```ts
+      * const marker = object.getComponent(UsageMarker);
+      * if (marker?.isUsed) {
+      *   console.log("Object is being used by:", marker.usedBy);
+      * }
+      * ```
+      *
+      * @summary Marks object as currently being interacted with
+      * @category Interactivity
+      * @group Components
+      * @see {@link DeleteBox} respects this marker
+      * @see {@link DragControls} adds this during drag
       */
      export declare class UsageMarker extends Component {
          isUsed: boolean;
@@ -16604,22 +18693,56 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.
-      * The USDZ file is generated using the Needle Engine ThreeUSDZExporter.
-      * The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.
-      * The exporter can automatically collect Animations and AudioSources and export them as playing at the start.
-      * The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.
-      * @example
-      * ```typescript
-      * const usdz = new USDZExporter();
-      * usdz.objectToExport = myObject;
-      * usdz.autoExportAnimations = true;
-      * usdz.autoExportAudioSources = true;
-      * usdz.exportAsync();
+      * USDZExporter creates USDZ files and opens them in Apple QuickLook on iOS/iPadOS/visionOS.
+      * Enables "View in AR" functionality for Apple devices directly from web experiences.
+      *
+      * **Key features:**
+      * - Auto-exports animations and audio sources
+      * - Interactive behaviors via Needle's "Everywhere Actions" system
+      * - RealityKit physics support (iOS 18+, visionOS 1+)
+      * - Custom QuickLook overlay with call-to-action buttons
+      * - Progressive texture/mesh LOD handling
+      *
+      * [![](https://cloud.needle.tools/-/media/YyUz1lUVlOhEY4fWZ-oMsA.gif)](https://engine.needle.tools/samples/?overlay=samples&tag=usdz)
+      *
+      * **Automatic setup:**
+      * - Creates QuickLook button on compatible devices
+      * - Respects {@link XRFlag} for AR-specific visibility
+      * - Handles {@link WebARSessionRoot} scale
+      *
+      * **Custom extensions:**
+      * Add custom behaviors by implementing {@link IUSDExporterExtension} and adding to {@link extensions} array.
+      *
+      * **Debug:** Use `?debugusdz` URL parameter. Press 'T' to trigger export.
+      *
+      * @example Basic USDZ export
+      * ```ts
+      * const exporter = myObject.addComponent(USDZExporter);
+      * exporter.objectToExport = productModel;
+      * exporter.autoExportAnimations = true;
+      * exporter.interactive = true; // Enable QuickLook behaviors
+      *
+      * // Trigger export
+      * await exporter.exportAndOpen();
+      * ```
+      *
+      * @example Custom branding
+      * ```ts
+      * exporter.customBranding = {
+      *   callToAction: "Buy Now",
+      *   checkoutTitle: "Product Name",
+      *   callToActionURL: "https://shop.example.com"
+      * };
       * ```
-      * @summary Export 3D objects as USDZ files for QuickLook
+      *
+      * @summary Export 3D objects as USDZ files for Apple QuickLook AR
       * @category XR
       * @group Components
+      * @see {@link WebXR} for WebXR-based AR/VR
+      * @see {@link WebARSessionRoot} for AR placement and scaling
+      * @see {@link XRFlag} for AR-specific object visibility
+      * @see {@link CustomBranding} for QuickLook overlay customization
+      * @link https://engine.needle.tools/samples/?overlay=samples&tag=usdz
       */
      export declare class USDZExporter extends Component {
          /** Called before the USDZ file is exported */
@@ -16805,7 +18928,37 @@ export declare class OrbitControls extends Component implements ICameraControlle
          userId: string;
      }
 
-     /** create accessor callbacks for a field */
+     /**
+      * Marks a field to trigger the `onValidate` callback when its value changes.
+      * Useful for reacting to property changes from the editor or at runtime.
+      *
+      * Your component must implement `onValidate(property?: string)` to receive notifications.
+      *
+      * @param set Optional custom setter called before the value is assigned
+      * @param get Optional custom getter called when the value is read
+      *
+      * @example Basic usage
+      * ```ts
+      * export class MyComponent extends Behaviour {
+      *   @serializable()
+      *   @validate()
+      *   color: Color = new Color(1, 0, 0);
+      *
+      *   onValidate(property?: string) {
+      *     if (property === "color") {
+      *       console.log("Color changed to:", this.color);
+      *     }
+      *   }
+      * }
+      * ```
+      * @example With custom setter
+      * ```ts
+      * @validate(function(value) {
+      *   console.log("Setting speed to", value);
+      * })
+      * speed: number = 1;
+      * ```
+      */
      export declare const validate: (set?: setter, get?: getter) => (target: IComponent | any, propertyKey: string, descriptor?: undefined) => void;
 
      declare type ValidLoaderReturnType = CustomModel | Object3D | BufferGeometry;
@@ -16929,18 +19082,45 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * The VideoPlayer component can be used to playback video clips from urls, streams or m3u8 playlists (livestreams)
-      * @example Add a video player component to a game object and set the url to a video file. The video will start playing once the object becomes active in your scene
-      * ```typescript
-      * // Add a video player component to a game object and set the url to a video file. The video will start playing once the object becomes active in your scene
+      * VideoPlayer plays video clips from URLs, media streams, or HLS playlists (m3u8 livestreams).
+      *
+      * **Supported formats:**
+      * - Standard video files (MP4, WebM, etc.)
+      * - Media streams (from webcam, screen capture, etc.)
+      * - HLS playlists (m3u8) for livestreaming
+      *
+      * ![](https://cloud.needle.tools/-/media/w1uHur5yu3Ni7qFaKIFX-g.gif)
+      *
+      * **Rendering modes:**
+      * Video can be rendered to a material texture, render texture, or camera planes.
+      * Set `targetMaterialRenderer` to apply video to a specific mesh's material.
+      *
+      * **Browser autoplay:**
+      * Videos may require user interaction to play with audio.
+      * Set `playOnAwake = true` for automatic playback (muted if needed).
+      *
+      * @example Basic video playback
+      * ```ts
       * const videoPlayer = addComponent(obj, VideoPlayer, {
-      *    url: "https://www.w3schools.com/html/mov_bbb.mp4",
-      *    playOnAwake: true,
+      *   url: "https://example.com/video.mp4",
+      *   playOnAwake: true,
+      *   loop: true,
       * });
       * ```
+      *
+      * @example Play video on a 3D surface
+      * ```ts
+      * const video = myScreen.getComponent(VideoPlayer);
+      * video.targetMaterialRenderer = myScreen.getComponent(Renderer);
+      * video.play();
+      * ```
+      *
       * @summary Plays video clips from URLs or streams
       * @category Multimedia
       * @group Components
+      * @see {@link AudioSource} for audio-only playback
+      * @see {@link ScreenCapture} for capturing and sharing video
+      * @see {@link Renderer} for video texture targets
       */
      export declare class VideoPlayer extends Component {
          /**
@@ -17193,11 +19373,42 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /* Excluded from this release type: VisibilityMode */
 
      /**
-      * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.
-      * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).
+      * Voice over IP (VoIP) component for real-time audio communication between users.
+      * Allows sending and receiving audio streams in networked rooms.
+      *
+      * **Requirements:**
+      * - Active network connection (via {@link SyncedRoom} or manual connection)
+      * - User permission for microphone access (requested automatically)
+      * - HTTPS connection (required for WebRTC)
+      *
+      * **Features:**
+      * - Automatic connection when joining rooms (`autoConnect`)
+      * - Background audio support (`runInBackground`)
+      * - Optional UI toggle button (`createMenuButton`)
+      * - Mute/unmute control
+      *
+      * **Debug:** Use `?debugvoip` URL parameter or set `debug = true` for logging.
+      * Press 'v' to toggle mute, 'c' to connect/disconnect when debugging.
+      *
+      * @example Enable VoIP in your scene
+      * ```ts
+      * const voip = myObject.addComponent(Voip);
+      * voip.autoConnect = true;
+      * voip.createMenuButton = true;
+      *
+      * // Manual control
+      * voip.connect();    // Start sending audio
+      * voip.disconnect(); // Stop sending
+      * voip.setMuted(true); // Mute microphone
+      * ```
+      *
       * @summary Voice over IP for networked audio communication
       * @category Networking
       * @group Components
+      * @see {@link SyncedRoom} for room management
+      * @see {@link NetworkedStreams} for the underlying streaming
+      * @see {@link ScreenCapture} for video streaming
+      * @link https://engine.needle.tools/docs/networking.html
       */
      export declare class Voip extends Component {
          /** When enabled, VoIP will start when a room is joined or when this component is enabled while already in a room.
@@ -17552,11 +19763,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
      declare type WebsocketSendType = IModel | object | boolean | null | string | number;
 
      /**
-      * Use the WebXR component to enable VR and AR on iOS and Android in your scene. VisionOS support is also provided via QuickLook USDZ export.
+      * Use the WebXR component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.
       *
       * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
       *
-      * - Example: https://samples.needle.tools/collaborative-sandbox
+      * ![](https://cloud.needle.tools/-/media/gcj_YoSns8FivafQRiCiOQ.gif)
+      *
       *
       * @example Enable VR and AR support using code
       * ```ts
@@ -17583,6 +19795,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @summary WebXR Component for VR and AR support
       * @category XR
       * @group Components
+      * @see {@link NeedleXRSession} for low-level XR API
+      * @see {@link XRControllerMovement} for VR locomotion
+      * @see {@link WebARSessionRoot} for AR session configuration
+      * @see {@link Avatar} for networked user avatars
+      * @link https://engine.needle.tools/docs/xr.html
+      * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
+      * @link https://engine.needle.tools/samples/collaborative-sandbox
       */
      export declare class WebXR extends Component {
          /**
@@ -17822,47 +20041,175 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Add this component to a object to enable image tracking in WebXR sessions.
+      * Create powerful AR image tracking experiences with just a few lines of code!
+      * WebXRImageTracking makes it incredibly easy to detect marker images in the real world and anchor 3D content to them.
+      * Needle Engine automatically handles all the complexity across different platforms and fallback modes for you.
+      *
+      * [![Image Tracking Demo](https://cloud.needle.tools/-/media/vRUf9BmqW_bgNARATjmfCQ.gif)](https://engine.needle.tools/samples/image-tracking)
+      *
+      * **What makes Needle Engine special:**
+      * - **Write once, run everywhere**: The same code works across iOS, Android, and visionOS
+      * - **Automatic platform optimization**: Seamlessly switches between WebXR, ARKit, and QuickLook
+      * - **Flexible deployment options**: From full WebXR with unlimited markers to QuickLook fallback
+      * - **Production ready**: Battle-tested tracking with adaptive smoothing and stability features
+      *
+      * **Platform Support & Options:**
+      * - **iOS (WebXR via AppClip)**: Full WebXR support - track unlimited markers simultaneously via native ARKit!
+      * - **iOS (QuickLook mode)**: Instant AR without app installation - perfect for quick demos (tracks first marker)
+      * - **Android (WebXR)**: Native WebXR Image Tracking API - unlimited markers (requires browser flag during early access)
+      * - **visionOS (QuickLook)**: Spatial image anchoring with Apple's AR QuickLook
+      *
+      * **Simple 3-Step Setup:**
+      * 1. Add this component to any GameObject in your scene
+      * 2. Configure your markers in the `trackedImages` array:
+      *    - `image`: URL to your marker image
+      *    - `widthInMeters`: Physical size of your printed marker
+      *    - `object`: The 3D content to display
+      * 3. Export and test - Needle handles the rest!
+      *
+      * **Pro Tips for Best Results:**
+      * - Use high-contrast markers with unique features for reliable tracking
+      * - Match `widthInMeters` to your actual physical marker size for accurate positioning
+      * - Enable `imageDoesNotMove` for wall posters or floor markers - significantly improves stability
+      * - Use `smooth` (enabled by default) for professional-looking, jitter-free tracking
+      * - Test with different marker sizes and lighting - Needle's adaptive tracking handles various conditions
+      *
+      * ![](https://cloud.needle.tools/-/media/V-2UxGVRJxvH9oDnXGnIdg.png)
+      * *WebXRImageTracking component in Unity Editor*
+      *
+      * ![](https://cloud.needle.tools/-/media/poDPca1bI1an4SBY7LtKNA.png)
+      * *WebXRImageTracking panel/component in Blender*
+      *
+      * @example Getting started - it's this easy!
+      * ```ts
+      * // Just add markers and Needle handles everything else
+      * const imageTracking = myObject.addComponent(WebXRImageTracking);
+      * const marker = new WebXRImageTrackingModel({
+      *   url: "https://example.com/my-poster.png",
+      *   widthInMeters: 0.3, // 30cm poster
+      *   object: my3DContent
+      * });
+      * imageTracking.addImage(marker);
+      * // Done! Works on iOS, Android, and visionOS automatically
+      * ```
       *
-      * You need to add at least one {@link WebXRImageTrackingModel} to the `trackedImages` array to define which images to track and which objects to place on top of them.
+      * @example Track multiple markers (WebXR mode)
+      * ```ts
+      * const imageTracking = myObject.addComponent(WebXRImageTracking);
       *
-      * **NOTE:** For Android devices, image tracking currently requires the user to enable the `chrome://flags/#webxr-incubations` flag in Chrome.
+      * // In WebXR mode (iOS AppClip, Android), all markers work simultaneously!
+      * const productBox = new WebXRImageTrackingModel({ url: "product-box.png", widthInMeters: 0.15, object: productInfo });
+      * const businessCard = new WebXRImageTrackingModel({ url: "business-card.png", widthInMeters: 0.09, object: contactCard });
+      * const poster = new WebXRImageTrackingModel({ url: "poster.png", widthInMeters: 0.5, object: videoPlayer });
       *
-      * **NOTE:** For iOS only one image can be tracked at a time. If you have multiple images in the `trackedImages` array, only the first one will be tracked. You can use the {@link setPrimaryImage} method to change which image is tracked before entering the XR session.
+      * imageTracking.addImage(productBox);
+      * imageTracking.addImage(businessCard);
+      * imageTracking.addImage(poster);
       *
-      * - Example: https://samples.needle.tools/image-tracking
+      * // For QuickLook fallback mode, optionally set which marker is primary
+      * imageTracking.setPrimaryImage(poster); // This will be used in QuickLook
+      * ```
       *
+      * @example Professional setup for static markers
+      * ```ts
+      * // Perfect for museums, retail displays, or permanent installations
+      * const wallArt = new WebXRImageTrackingModel({
+      *   url: "gallery-painting.png",
+      *   widthInMeters: 0.6,
+      *   object: interactiveExplanation,
+      *   imageDoesNotMove: true, // Rock-solid tracking for static markers!
+      *   hideWhenTrackingIsLost: false // Content stays visible even if temporarily occluded
+      * });
+      * ```
+      *
+      * **Why developers love Needle's image tracking:**
+      * - Zero platform-specific code required
+      * - Automatic graceful degradation across deployment modes
+      * - Built-in jitter reduction and stability features
+      * - Works with any image - posters, packaging, business cards, artwork
+      * - Export once, deploy everywhere
+      *
+      * @summary The easiest way to create cross-platform AR image tracking experiences
       * @category XR
       * @group Components
+      * @see {@link WebXRImageTrackingModel} for marker configuration options
+      * @see {@link WebXRTrackedImage} for runtime tracking data and events
+      * @see {@link WebXR} for general WebXR setup and session management
+      * @link https://engine.needle.tools/docs/xr.html#image-tracking - Full Documentation
+      * @link https://engine.needle.tools/samples/image-tracking - Try Live Demo
+      * @link https://github.com/immersive-web/marker-tracking/blob/main/explainer.md - WebXR Marker Tracking Specification
       */
      export declare class WebXRImageTracking extends Component {
          /**
-          * If you have multiple images in your application to track then this method is useful for iOS AR where only the first image can be tracked.
-          * Call this method will set the given image as the first one in the array so it will be used for tracking.
+          * Set which marker should be primary (first in the list).
+          * Useful when deploying to QuickLook mode where one marker is tracked at a time.
+          * In full WebXR mode (iOS AppClip, Android), all markers track simultaneously regardless of order.
+          *
+          * **Note:** Needle Engine automatically adapts - in WebXR all markers work, in QuickLook the primary is used.
+          *
+          * @param image The marker model to set as primary
+          *
+          * @example
+          * ```ts
+          * // Great for offering different AR experiences from one deployment
+          * imageTracking.setPrimaryImage(businessCardMarker); // Use this for QuickLook
+          * // In WebXR mode, all markers still work simultaneously!
+          * ```
           */
          setPrimaryImage(image: WebXRImageTrackingModel): void;
          /**
-          * Add an image to track. If the image is already in the trackedImages array it won't be added again.
-          * Note: that adding images at runtime *while* in AR is not supported.
+          * Add a marker to track - it's that simple!
+          * Needle Engine handles all the platform differences automatically.
+          *
+          * **Tip:** Add all your markers upfront. In WebXR mode they all work simultaneously.
+          * In QuickLook mode, the first (primary) marker is used.
+          *
+          * @param image The marker configuration to add
+          * @param asPrimary Set to true to make this the primary marker (for QuickLook fallback)
           *
           * @example
           * ```ts
-          * const imageTracking = GameObject.getComponent(myGameObject, WebXRImageTracking);
-          * const image = new WebXRImageTrackingModel({ url: "https://example.com/my-marker.png", widthInMeters: 0.2, object: myObject });
-          * imageTracking.addImage(image, true); // add and set as primary image
+          * // Super simple - works across all platforms
+          * const marker = new WebXRImageTrackingModel({
+          *   url: "https://mysite.com/poster.png",
+          *   widthInMeters: 0.42, // A3 poster width
+          *   object: cool3DModel
+          * });
+          * imageTracking.addImage(marker);
+          * // That's it! Needle does the rest.
           * ```
           */
          addImage(image: WebXRImageTrackingModel, asPrimary?: boolean): void;
          /**
-          * List of images to track in the WebXR session. Use {@link WebXRImageTrackingModel} to define each image and the object to place on top of it.
+          * Your list of markers to track. Add as many as you need!
           *
-          * Use the `addImage()` and `setPrimaryImage()` methods to modify this array at runtime.
+          * **How it works across platforms:**
+          * - **WebXR mode** (iOS AppClip, Android): All markers are tracked simultaneously - amazing for multi-marker experiences!
+          * - **QuickLook mode** (iOS fallback, visionOS): First marker is used - perfect for quick demos without app installation
+          *
+          * **Needle's smart deployment:** Configure all your markers once, and Needle automatically uses the best
+          * tracking mode available on each platform. No platform-specific code needed!
+          *
+          * @see {@link WebXRImageTrackingModel} for marker configuration
+          * @see {@link addImage} and {@link setPrimaryImage} for runtime management
           */
          readonly trackedImages: WebXRImageTrackingModel[];
-         /** Applies smoothing based on detected jitter to the tracked image. */
+         /**
+          * Enable Needle's professional-grade adaptive smoothing for rock-solid tracking.
+          * Automatically reduces jitter while staying responsive to real movement.
+          *
+          * **Pro tip:** Keep this enabled (default) for production experiences!
+          *
+          * @default true
+          */
          smooth: boolean;
          private readonly trackedImageIndexMap;
-         /** @returns true if image tracking is supported on this device. This may return false at runtime if the user's browser did not enable webxr incubations */
+         /**
+          * Check if image tracking is available on this device right now.
+          *
+          * **Note:** On Android Chrome, WebXR Image Tracking is currently behind a flag during the early access period.
+          * Needle automatically falls back to other modes when needed, so your experience keeps working!
+          */
          get supported(): boolean;
          private _supported;
          /* Excluded from this release type: awake */
@@ -17880,12 +20227,36 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * WebXRImageTracking allows you to track images in the real world and place objects on top of them.
-      * This component is only available in WebXR sessions.
-      * The WebXRImageTrackingModel contains the image to track, the object to place on top of the image, and the size of the image as well as settings for the tracking.
-      * Used by the {@link WebXRImageTracking} component
+      * Configuration model for a tracked image marker.
+      * Defines which image to track, its physical size, and which 3D content to display when detected.
+      *
+      * **Important:** The physical size (`widthInMeters`) must match your printed marker size for accurate tracking.
+      * Mismatched sizes cause the tracked object to appear to "float" above or below the marker.
+      *
+      * **Best practices for marker images:**
+      * - Use high-contrast images with distinct features
+      * - Avoid repetitive patterns or solid colors
+      * - Test images at intended viewing distances
+      * - Ensure good lighting conditions
+      *
+      * @summary Configuration for a single trackable image marker
+      * @category XR
+      * @see {@link WebXRImageTracking} for the component that uses these models
+      * @link https://engine.needle.tools/docs/xr.html#image-tracking
+      * @link https://engine.needle.tools/samples/image-tracking
       */
      export declare class WebXRImageTrackingModel {
+         /**
+          * Creates a new image tracking configuration.
+          *
+          * @param params Configuration parameters
+          * @param params.url URL to the marker image to track
+          * @param params.widthInMeters Physical width of the printed marker in meters (must match real size!)
+          * @param params.object The 3D object or AssetReference to display when this image is detected
+          * @param params.createObjectInstance If true, creates a new instance for each detection (useful for tracking multiple instances of the same marker)
+          * @param params.imageDoesNotMove Enable for static markers (floor/wall mounted) to improve tracking stability
+          * @param params.hideWhenTrackingIsLost If true, hides the object when tracking is lost; if false, leaves it at the last known position
+          */
          constructor(params: {
              url: string;
              widthInMeters: number; /** Object to track */
@@ -17895,32 +20266,75 @@ export declare class OrbitControls extends Component implements ICameraControlle
              hideWhenTrackingIsLost?: boolean;
          });
          /**
-          * Tracked image marker url. Make sure the image has good contrast and unique features to improve the tracking quality.
+          * URL to the marker image to track.
+          * **Important:** Use images with high contrast and unique features to improve tracking quality.
+          * Avoid repetitive patterns, solid colors, or low-contrast images.
           */
          image?: string;
-         /** Make sure this matches your physical marker size! Otherwise the tracked object will \"swim\" above or below the marker.
-          * @default 0.25 which is equivalent to 25cm
+         /**
+          * Physical width of the printed marker in meters.
+          * **Critical:** This must match your actual printed marker size!
+          * If mismatched, the tracked object will appear to "float" above or below the marker.
+          *
+          * @default 0.25 (25cm)
+          * @example
+          * ```ts
+          * // For a business card sized marker (9cm wide)
+          * widthInMeters = 0.09;
+          *
+          * // For an A4 page width (21cm)
+          * widthInMeters = 0.21;
+          * ```
           */
          widthInMeters: number;
          /**
-          * The object moved around by the image. Make sure the size matches WidthInMeters.
+          * The 3D object or prefab to display when this marker is detected.
+          * The object will be positioned and rotated to match the tracked image in the real world.
+          *
+          * **Note:** Scale your 3D content appropriately relative to `widthInMeters`.
           */
          object?: AssetReference;
          /**
-          * If true, a new instance of the referenced object will be created for each tracked image. Enable this if you're re-using objects for multiple markers.
+          * When enabled, creates a new instance of the referenced object each time this image is detected.
+          * Enable this if you want to track multiple instances of the same marker simultaneously,
+          * or if the same object is used for multiple different markers.
+          *
+          * @default false
           */
          createObjectInstance: boolean;
-         /** Use this for static images (e.g. markers on the floor). Only the first few frames of new poses will be applied to the model. This will result in more stable tracking.
+         /**
+          * Enable for static markers that don't move (e.g., posters on walls or markers on the floor).
+          * When enabled, only the first few tracking frames are used to position the object,
+          * resulting in more stable tracking by ignoring subsequent minor position changes.
+          *
+          * **Use cases:**
+          * - Wall-mounted posters or artwork
+          * - Floor markers for persistent AR content
+          * - Product packaging on shelves
+          *
+          * **Don't use for:**
+          * - Handheld cards or objects
+          * - Moving markers
+          *
           * @default false
           */
          imageDoesNotMove: boolean;
          /**
-          * Enable to hide the tracked object when the image is not tracked anymore. When disabled the tracked object will stay at the position it was last tracked at.
+          * Controls visibility behavior when tracking is lost.
+          * - When `true`: Object is hidden when the marker is no longer visible
+          * - When `false`: Object remains visible at its last tracked position
+          *
           * @default true
           */
          hideWhenTrackingIsLost: boolean;
          /**
-          * Get the name of the image file from the url
+          * Extracts the filename from the marker image URL.
+          * @returns The filename (last part of the URL path), or null if no image URL is set
+          * @example
+          * ```ts
+          * // URL: "https://example.com/markers/business-card.png"
+          * // Returns: "business-card.png"
+          * ```
           */
          getNameFromUrl(): string | null;
      }
@@ -17990,17 +20404,58 @@ export declare class OrbitControls extends Component implements ICameraControlle
          context: XRPlaneContext;
      };
 
+     /**
+      * Represents a tracked image detected during a WebXR session.
+      * Contains position, rotation, and tracking state information for a detected marker image.
+      *
+      * **Properties:**
+      * - Access image URL and physical dimensions
+      * - Get current position and rotation in world space
+      * - Check tracking state (tracked vs emulated)
+      * - Apply transform to 3D objects
+      *
+      * @summary Runtime data for a detected marker image in WebXR
+      * @category XR
+      */
      export declare class WebXRTrackedImage {
+         /** URL of the tracked marker image */
          get url(): string;
+         /** Physical width of the marker in meters */
          get widthInMeters(): number;
+         /** The ImageBitmap used for tracking */
          get bitmap(): ImageBitmap;
+         /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
          get model(): WebXRImageTrackingModel;
+         /**
+          * The measured size of the detected image in the real world.
+          * May differ from `widthInMeters` if the physical marker doesn't match the configured size.
+          */
          readonly measuredSize: number;
+         /**
+          * Current tracking state of the image:
+          * - `tracked` - Image is currently being tracked by the system
+          * - `emulated` - Tracking is being emulated (less accurate)
+          */
          readonly state: "tracked" | "emulated";
-         /** Copy the image position to a vector */
+         /**
+          * Copy the current world position of the tracked image to a Vector3.
+          * @param vec The vector to store the position in
+          * @returns The input vector with the position copied to it
+          */
          getPosition(vec: Vector3): Vector3;
-         /** Copy the image rotation to a quaternion */
+         /**
+          * Copy the current world rotation of the tracked image to a Quaternion.
+          * @param quat The quaternion to store the rotation in
+          * @returns The input quaternion with the rotation copied to it
+          */
          getQuaternion(quat: Quaternion): Quaternion;
+         /**
+          * Apply the tracked image's position and rotation to a 3D object.
+          * Optionally applies smoothing to reduce jitter.
+          *
+          * @param object The 3D object to update
+          * @param t01 Interpolation factor (0-1) for smoothing. If undefined or >= 1, no smoothing is applied. When smoothing is enabled, larger position/rotation changes will automatically reduce the smoothing to prevent lag.
+          */
          applyToObject(object: Object3D, t01?: number | undefined): void;
          private static _positionBuffer;
          private static _rotationBuffer;
@@ -18195,12 +20650,39 @@ export declare class OrbitControls extends Component implements ICameraControlle
      declare type XRControllerType = "hand" | "controller";
 
      /**
-      * Use the XRFlag component to show or hide objects based on the current XR state or session.
-      * This means you can show or hide objects based on if the user is in VR, AR, using first person view or third person view.
+      * XRFlag shows or hides GameObjects based on the current XR state or session.
+      * Use for XR-responsive content that should only appear in specific modes.
+      *
+      * **XR states:**
+      * - `Browser` - Normal web browsing (no XR)
+      * - `AR` - Augmented reality session
+      * - `VR` - Virtual reality session
+      * - `FirstPerson` - First-person view mode
+      * - `ThirdPerson` - Third-person/spectator view mode
+      * - Combine with bitwise OR: `AR | VR`
+      *
+      * **Debug options:**
+      * - `?debugxrflags` - Log flag changes
+      * - `?disablexrflags` - Disable all XR flags
+      *
+      * @example Show only in VR
+      * ```ts
+      * const flag = myObject.addComponent(XRFlag);
+      * flag.visibleIn = XRStateFlag.VR;
+      * ```
+      *
+      * @example Show in AR and VR, hide in browser
+      * ```ts
+      * flag.visibleIn = XRStateFlag.AR | XRStateFlag.VR;
+      * ```
       *
       * @category XR
       * @category Utilities
       * @group Components
+      * @see {@link XRStateFlag} for state options
+      * @see {@link XRState} for global state management
+      * @see {@link DeviceFlag} for device-based visibility
+      * @see {@link WebXR} for XR session management
       */
      export declare class XRFlag extends Component {
          private static registry;