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

package/src/engine-components/NestedGltf.ts

@@ -8,26 +8,62 @@ import { EventList } from "./EventList.js";
 
 const debug = getParam("debugnestedgltf");
 
-/** 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 class NestedGltf extends Behaviour {
 
-    /**  A reference to the gltf file that should be loaded */
+    /** Reference to the glTF file to load. Can be a URL or asset path. */
     @serializable(AssetReference)
     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.
+     */
     @serializable(EventList)
     loaded: EventList<{ component: NestedGltf, instance: any, asset: AssetReference }> = new EventList();
 
     /**
      * EXPERIMENTAL for cloud asset loading
      */
+    @serializable()
     loadAssetInParent = true;
 
 

package/src/engine-components/OffsetConstraint.ts

@@ -5,11 +5,35 @@ import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * 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 class OffsetConstraint extends Behaviour {
 

package/src/engine-components/OrbitControls.ts

@@ -60,12 +60,50 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
     }
 }
 
-/** 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 class OrbitControls extends Behaviour implements ICameraController {
 

package/src/engine-components/ReflectionProbe.ts

@@ -15,13 +15,28 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 const $originalMaterial = Symbol("original material");
 
 /**
- * A ReflectionProbe provides reflection data to materials within its defined area.
- * 
- * - Sample: http://samples.needle.tools/reflection-probes
- * 
+ * 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  
+ *
+ * **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 class ReflectionProbe extends Behaviour {
 
@@ -45,7 +60,6 @@ export class ReflectionProbe extends Behaviour {
                             return probe;
                         }
                     }
-                    // TODO not supported right now, as we'd have to pass the ReflectionProbe scale through as well.
                     else if (probe.isInBox(object)) {
                         if (debug) console.log("Found reflection probe", object.name, probe.name);
                         return probe;
@@ -137,7 +151,7 @@ export class ReflectionProbe extends Behaviour {
     // and some need reflection probe and some don't
     // we need to make sure we don't override the material but use a copy
 
-    private static _rendererMaterialsCache: Map<IRenderer, Array<{ material: Material, copy: Material }>> = new Map();
+    private static _rendererMaterialsCache: Map<IRenderer, Array<{ material: Material, copy: Material, originalVersion: number }>> = new Map();
 
     onSet(_rend: IRenderer) {
         if (disable) return;
@@ -171,15 +185,16 @@ export class ReflectionProbe extends Behaviour {
             let cached = rendererCache[i];
 
             // make sure we have the currently assigned material cached (and an up to date clone of that)
-            // TODO: this is causing problems with progressive textures sometimes (depending on the order) when the version changes and we re-create materials over and over. We might want to just set the material envmap instead of making a clone
+            // Compare against the stored original version, not the clone's version (which gets modified by needsUpdate)
+            // This prevents cloning materials every frame when onUnset restores the original material
             const isCachedInstance = material === cached?.copy;
-            const hasChanged = !cached || cached.material.uuid !== material.uuid || cached.copy.version !== material.version;
+            const hasChanged = !cached || cached.material.uuid !== material.uuid || cached.originalVersion !== material.version;
             if (!isCachedInstance && hasChanged) {
                 if (debug) {
                     let reason = "";
                     if (!cached) reason = "not cached";
                     else if (cached.material !== material) reason = "reference changed; cached instance?: " + isCachedInstance;
-                    else if (cached.copy.version !== material.version) reason = "version changed";
+                    else if (cached.originalVersion !== material.version) reason = "version changed";
                     console.warn("Cloning material", material.name, material.version, "Reason:", reason, "\n", material.uuid, "\n", cached?.copy.uuid, "\n", _rend.name);
                 }
 
@@ -189,11 +204,13 @@ export class ReflectionProbe extends Behaviour {
                 if (cached) {
                     cached.copy = clone;
                     cached.material = material;
+                    cached.originalVersion = material.version;
                 }
                 else {
                     cached = {
                         material: material,
-                        copy: clone
+                        copy: clone,
+                        originalVersion: material.version
                     };
                     rendererCache.push(cached);
                 }
@@ -213,9 +230,10 @@ export class ReflectionProbe extends Behaviour {
             const copy = cached?.copy;
 
             if ("envMap" in copy) {
-                // make sure the reflection probe is assigned
-                copy.envMap = this.texture;
-                copy.needsUpdate = true;
+                if (copy.envMap !== this.texture) {  // Only update if changed
+                    copy.envMap = this.texture;
+                    copy.needsUpdate = true;
+                }       
             }
 
             _rend.sharedMaterials[i] = copy;

package/src/engine-components/Renderer.ts

@@ -200,8 +200,42 @@ class SharedMaterialArray implements ISharedMaterials {
 }
 
 /**
+ * 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 class Renderer extends Behaviour implements IRenderer {
 
@@ -691,7 +725,6 @@ export class Renderer extends Behaviour implements IRenderer {
         }
 
         if (this.reflectionProbeUsage !== ReflectionProbeUsage.Off && this._reflectionProbe) {
-            if (!this._lightmaps?.length) // Currently reflectionprobes cant be used with lightmaps
                 this._reflectionProbe.onSet(this);
         }
         // since three 163 we need to set the envMap to the scene envMap if it is not set

package/src/engine-components/SceneSwitcher.ts

@@ -84,6 +84,13 @@ export interface ISceneEventListener {
  * - [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.
  * 
@@ -111,6 +118,10 @@ export interface ISceneEventListener {
  * @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 class SceneSwitcher extends Behaviour {
 

package/src/engine-components/ScreenCapture.ts

@@ -61,19 +61,51 @@ export declare type ScreenCaptureOptions = {
     deviceFilter?: (device: MediaDeviceInfo) => boolean,
 }
 
-/** 
- * 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.  
- * 
- * Note: For debugging append `?debugscreensharing` to the URL to see more information in the console.
- * 
- * 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.
+/**
+ * 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.    
+ *
+ * **Supported capture devices:**  
+ * - `Screen` - Share desktop/window/tab
+ * - `Camera` - Share webcam feed
+ * - `Microphone` - Audio only
+ * - `Canvas` - Share the 3D canvas (experimental)
  * 
+ * ![](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 class ScreenCapture extends Behaviour implements IPointerClickHandler {
 
     /**

package/src/engine-components/Skybox.ts

@@ -443,7 +443,7 @@ function tryParseMagicSkyboxName(str: string | null | undefined, environment: bo
         return useLowRes ? value.url_low : value.url;
     }
     else if (typeof str === "string" && str?.length && (isDevEnvironment() || debug)) {
-        const noUrlOrFile = !str.startsWith("http") && !str.startsWith("file:") && !str.startsWith("blob:") && !str.startsWith("data:");
+        const noUrlOrFile = !str.startsWith("http") && !str.startsWith("file:") && !str.startsWith("blob:") && !str.startsWith("data:") && !str.startsWith("/")
         if(noUrlOrFile) {
             console.warn(`RemoteSkybox: Unknown magic skybox name "${str}". Valid names are: ${Object.keys(MagicSkyboxNames).map(n => `"${n}"`).join(", ")}`);
         }

package/src/engine-components/SmoothFollow.ts

@@ -6,12 +6,57 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getWorldPosition, getWorldQuaternion } from "../engine/engine_three_utils.js";
 import { Behaviour } from "./Component.js";
 
+import type { LookAt } from "./api.js";
+
 /**
- * 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 class SmoothFollow extends Behaviour {
 
@@ -22,21 +67,34 @@ export class SmoothFollow extends Behaviour {
     target: Object3D | null = 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
      */
     @serializable()
     followFactor = .1;
+
     /**
-     * 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
      */
     @serializable()
     rotateFactor = .1;
 
+    /**
+     * Which position axes to follow. Use bitwise OR to combine:
+     * `Axes.X | Axes.Y` follows only X and Y axes.
+     * @default Axes.All
+     */
     @serializable()
     positionAxes: Axes = Axes.All;
 
+    /** When true, rotates 180° around Y axis (useful for mirrored setups) */
     flipForward: boolean = false;
 
     private static _invertForward: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
@@ -49,6 +107,10 @@ export class SmoothFollow extends Behaviour {
         this.updateNow(false);
     }
 
+    /**
+     * Manually update the position/rotation to follow the target.
+     * @param hard If true, snaps instantly to target without smoothing
+     */
     updateNow(hard: boolean) {
         if (!this.target || this.target === this.gameObject) return;
         if (this.followFactor > 0) {

package/src/engine-components/SpatialTrigger.ts

@@ -24,11 +24,34 @@ function testMask(mask1, mask2) {
 }
 
 /**
- * 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.
+ * 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 class SpatialTriggerReceiver extends Behaviour {
 
@@ -126,10 +149,34 @@ export class SpatialTriggerReceiver extends Behaviour {
 }
 
 /**
- * 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
+ * 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.  
+ *
+ * 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 class SpatialTrigger extends Behaviour {
 

package/src/engine-components/SpectatorCamera.ts

@@ -31,14 +31,32 @@ export enum SpectatorMode {
 const debug = getParam("debugspectator");
 
 /**
- * Provides functionality to follow and spectate other users in a networked environment.
- * Handles camera switching, following behavior, and network synchronization for spectator mode.
- * 
- * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
- * 
+ * 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:** 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 class SpectatorCamera extends Behaviour {
 

package/src/engine-components/SyncedRoom.ts

@@ -33,9 +33,15 @@ const debug = utils.getParam("debugsyncedroom");
  * 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 class SyncedRoom extends Behaviour {