@needle-tools/engine 4.13.0 → 4.13.1-next.6cb1b73

package/src/engine-components/LookAtConstraint.ts

@@ -1,37 +1,55 @@
 import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
+import type { LookAt } from "./api.js";
 import { Behaviour } from "./Component.js";
 import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
- * This component is used by {@link OrbitControls} internally.
- * 
- * @summary Look At Constraint for OrbitControls
+ * The [LookAtConstraint](https://engine.needle.tools/docs/api/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.  
+ *
+ * **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 class LookAtConstraint extends Behaviour {
 
     /**
-     * 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.
      */
     @serializable()
     constraintActive: boolean = true;
+
     /**
-     * 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.
      */
     @serializable()
     locked: boolean = false;
+
     /**
-     * The sources to look at.
+     * Objects to look at. The first object in the array is used
+     * as the primary look-at target.
      */
     @serializable(Object3D)
     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) {
         const source = this.sources[0];

package/src/engine-components/NeedleMenu.ts

@@ -3,16 +3,38 @@ import { serializable } from '../engine/engine_serialization.js';
 import { DeviceUtilities } from '../engine/engine_utils.js';
 import { Behaviour } from './Component.js';
 
-/** 
- * 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](https://engine.needle.tools/docs/api/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.    
  * 
- * Controls display options, button visibility, and menu positioning.
- * From code, you can access the menu via {@link Context.menu}. 
- * 
- * @summary Configuration component for the Needle Menu
+ * ![](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.
+ *
+ * @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 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 class NeedleMenu extends Behaviour {
 

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
+ * The [OffsetConstraint](https://engine.needle.tools/docs/api/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](https://engine.needle.tools/docs/api/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/PlayerColor.ts

@@ -7,7 +7,7 @@ import { Behaviour, GameObject } from "./Component.js";
 import { AvatarMarker } from "./webxr/WebXRAvatar.js";
 
 /**
- * PlayerColor assigns a unique color for each user in the room to the object it is attached to.  
+ * [PlayerColor](https://engine.needle.tools/docs/api/PlayerColor) Assigns a unique color for each user in the room to the object it is attached to.  
  * The color is generated based on the user's ID.
  * 
  * @summary Assigns a unique color to the player object

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
- * 
+ * The [ReflectionProbe](https://engine.needle.tools/docs/api/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;

package/src/engine-components/Renderer.ts

@@ -200,8 +200,43 @@ class SharedMaterialArray implements ISharedMaterials {
 }
 
 /**
+ * The [Renderer](https://engine.needle.tools/docs/api/Renderer) component 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 or Blender.  
+ * Access via the associated {@link RendererLightmap} component.    
+ * 
+ * [![](https://cloud.needle.tools/-/media/Vk944XVswtPEuxlNPLMxPQ.gif)](https://engine.needle.tools/samples/multiple-lightmaps/)
+ *
+ * **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
  */
 export class Renderer extends Behaviour implements IRenderer {
 
@@ -691,7 +726,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/RigidBody.ts

@@ -2,14 +2,18 @@ import { Matrix4, Object3D, Quaternion, Vector3, Vector3Like } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
 import { MODULES } from "../engine/engine_modules.js";
+import type { Physics } from "../engine/engine_physics.js";
 import { CollisionDetectionMode, RigidbodyConstraints } from "../engine/engine_physics.types.js";
+import type { RapierPhysics } from "../engine/engine_physics_rapier.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Context, FrameEvent } from "../engine/engine_setup.js";
-import { getWorldPosition } from "../engine/engine_three_utils.js";
 import type { IRigidbody, Vec3 } from "../engine/engine_types.js";
 import { validate } from "../engine/engine_util_decorator.js";
 import { delayForFrames, Watch } from "../engine/engine_utils.js";
+import type { CharacterController } from "./CharacterController.js";
+import type { BoxCollider, CapsuleCollider, Collider,MeshCollider, SphereCollider } from "./Collider.js";
 import { Behaviour } from "./Component.js";
+import type { Joint } from "./Joints.js";
 
 class TransformWatch {
 
@@ -134,15 +138,67 @@ class TransformWatch {
 }
 
 /**
- * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.   
+ * Rigidbody component for realistic physics simulation and dynamic interactions.  
+ * Used together with a {@link Collider} to enable physical behavior like gravity, collisions,  
+ * forces, and constraints. Powered by the Rapier physics engine.    
  * 
- * - Example: https://samples.needle.tools/physics-basic
- * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation
- * 
- * @summary Rigidbody for physical interactions
- * @category Physics 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * **Key features:**
+ * - Dynamic, kinematic, or static body types
+ * - Automatic or manual mass calculation
+ * - Gravity, drag, and angular drag control
+ * - Position and rotation constraints (locking axes)
+ * - Force, impulse, and velocity manipulation
+ * - Sleep/wake optimization for performance
+ * - Continuous collision detection (CCD) support
+ *
+ * @example Basic dynamic rigidbody
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.useGravity = true;
+ * rb.mass = 2.0;
+ * rb.drag = 0.5;
+ * ```
+ *
+ * @example Apply force to move object
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.applyForce(new Vector3(0, 10, 0)); // Upward force
+ * rb.applyImpulse(new Vector3(5, 0, 0)); // Instant velocity change
+ * ```
+ *
+ * @example Kinematic rigidbody (manually controlled)
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.isKinematic = true; // Not affected by forces
+ * rb.teleport({ x: 0, y: 5, z: 0 }); // Move without physics
+ * ```
+ *
+ * @example Lock rotation on Y axis (useful for characters)
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * rb.lockRotationY = true;
+ * // Or use constraints for multiple axes:
+ * rb.constraints = RigidbodyConstraints.FreezeRotationY | RigidbodyConstraints.FreezePositionZ;
+ * ```
+ *
+ * @summary Enables physics simulation with forces, gravity, and collisions
+ * @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 Collider} for collider base class
+ * @see {@link CharacterController} for character movement
+ * @see {@link Joint} for connecting bodies
+ * @see {@link RapierPhysics} for physics engine implementation
+ * @see {@link Physics} for raycasting and physics utilities
+ * @link https://engine.needle.tools/samples/physics-basic/
+ * @link https://engine.needle.tools/samples/physics-playground/
+ * @link https://engine.needle.tools/samples/physics-&-animation/
+ * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies
  */
 export class Rigidbody extends Behaviour implements IRigidbody {
 

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,52 @@ 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
+ * @category Multimedia
  * @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/SeeThrough.ts

@@ -6,9 +6,11 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getTempVector } from "../engine/engine_three_utils.js";
 import { getParam } from "../engine/engine_utils.js";
 import { USDObject, USDZExporterContext } from "./api.js";
+import type { Camera } from "./Camera.js";
 import { Behaviour } from "./Component.js";
 import { IUSDExporterExtension } from "./export/usdz/Extension.js";
 import { USDZExporter } from "./export/usdz/USDZExporter.js";
+import type { OrbitControls } from "./OrbitControls.js";
 import { Renderer } from "./Renderer.js";
 
 const debugSeeThrough = getParam("debugseethrough");
@@ -32,17 +34,82 @@ let i = 0;
 
 
 /**
- * Makes the object fade out when it is obscuring the reference point from the camera. This component can be put on any object in the scene. It will affect all Renderer components on the same object and child objects. 
- * 
- * Useful for e.g. making walls transparent when the camera is outside or hiding object's that would otherwise block the view.  
- * 
- * Requires a Renderer component on the same object or a child object.
- * 
- * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
- * 
- * @summary Makes objects fade out when obscuring a reference point from the camera
+ * Automatically fades objects to transparent when they obscure a reference point from the camera's view.  
+ * Perfect for architectural visualization, third-person games, or any scenario where objects should  
+ * become see-through when blocking the view of important content.  
+ *
+ * [![](https://cloud.needle.tools/-/media/1gbMOJLgTlXOug_g6xeKfg.gif)](https://engine.needle.tools/samples/see-through)
+ *
+ * **How it works:**  
+ * - Monitors the angle between the camera, this object, and a reference point
+ * - When the object blocks the view to the reference point, it fades out
+ * - Automatically affects all {@link Renderer} components on this object and children
+ * - Supports both transparent fading and alpha hash (dithered) fading
+ *
+ * **Key Features:**  
+ * - Smooth fade transitions with configurable duration
+ * - Optional alpha hash for maintaining opaque rendering (better performance)
+ * - Automatic or manual update modes
+ * - Disables raycasting when faded (objects become click-through)
+ * - Preserves original material properties when re-enabled
+ *
+ * **Configuration:**
+ * - `referencePoint` - Object to keep visible (defaults to scene root)
+ * - `fadeDuration` - Transition speed (default: 0.05 seconds)
+ * - `minAlpha` - Minimum opacity when faded (default: 0 = fully transparent)
+ * - `useAlphaHash` - Use dithered transparency instead of true transparency (default: true)
+ *
+ * **Performance:**
+ * - Materials are cloned once per renderer to avoid affecting shared materials
+ * - Updates direction calculation every 20 frames by default (configurable via `autoUpdate`)
+ * - Use `needsUpdate = true` to force immediate recalculation
+ *
+ * **Requirements:**
+ * Requires at least one {@link Renderer} component on the same object or child objects.
+ *
+ * @example Make walls transparent when blocking view
+ * ```ts
+ * // Add to walls or obstacles
+ * const seeThrough = wall.addComponent(SeeThrough);
+ * seeThrough.referencePoint = player; // Keep player visible
+ * seeThrough.fadeDuration = 0.2; // Smooth fade
+ * seeThrough.minAlpha = 0.2; // Slightly visible when faded
+ * ```
+ *
+ * @example Third-person camera with see-through objects
+ * ```ts
+ * const character = GameObject.findByName("Character");
+ * const obstacles = GameObject.findByTag("Obstacle");
+ *
+ * for (const obstacle of obstacles) {
+ *   const st = obstacle.addComponent(SeeThrough);
+ *   st.referencePoint = character;
+ *   st.useAlphaHash = true; // Better performance
+ * }
+ * ```
+ *
+ * @example Manual control of see-through effect
+ * ```ts
+ * const seeThrough = this.gameObject.getComponent(SeeThrough);
+ * if (seeThrough) {
+ *   seeThrough.autoUpdate = false; // Disable automatic fading
+ *
+ *   // Manually control transparency
+ *   seeThrough.updateAlpha(0.5, 0.3); // Fade to 50% over 0.3 seconds
+ *
+ *   // Or use override for precise control
+ *   seeThrough.overrideAlpha = 0.8; // Force 80% opacity
+ * }
+ * ```
+ *
+ * @summary Fades objects when they obscure the camera's view of a reference point
  * @category Rendering
  * @group Components
+ * @see {@link Renderer} for material/rendering control (required)
+ * @see {@link Camera} for camera setup and configuration
+ * @see {@link OrbitControls} for camera controls in similar use cases
+ * @link https://see-through-walls-z23hmxbz1kjfjn.needle.run/ for live demo
+ * @link https://engine.needle.tools/samples/see-through for sample project
  */
 export class SeeThrough extends Behaviour {