@needle-tools/engine 4.13.1-beta → 4.13.1-next.9fc3e64

package/src/engine/engine_utils_screenshot.ts

@@ -32,6 +32,7 @@ declare type ScreenshotImageMimeType = "image/webp" | "image/png" | "image/jpeg"
  * const dataUrl = screenshot();
  * saveImage(dataUrl, "screenshot.png");
  * ```
+ * 
  */
 export function screenshot(context?: Context, width?: number, height?: number, mimeType: ScreenshotImageMimeType = "image/webp", camera?: Camera | null): string | null {
     return screenshot2({ context, width, height, mimeType, camera });
@@ -106,12 +107,30 @@ export declare type ScreenshotOptionsBlob = ScreenshotOptions & {
 }
 
 export declare type ScreenshotOptionsShare = ScreenshotOptions & {
+    /**
+     * Set `{ type: "share" }` to share the screenshot using the Web Share API. The promise will resolve with the blob of the screenshot and whether it was shared successfully or not. Note that the Web Share API is only available in secure contexts (HTTPS) and on some platforms.
+     */
     type: "share",
+    /**
+     * The filename to use when sharing the screenshot. If not provided, a default filename will be used.
+     */
     filename?: string,
+    /**
+     * The mime type of the shared file. If not provided, the mime type will be inferred from the screenshot options or default to "image/png".
+     */
     file_type?: ScreenshotImageMimeType,
 
+    /**
+     * The title to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+     */
     title?: string,
+    /**
+     * The text to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+     */
     text?: string,
+    /**
+     * The URL to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+     */
     url?: string,
 }
 
@@ -120,36 +139,241 @@ declare type ScreenshotOptionsShareReturnType = {
     shared: boolean,
 }
 
-/** 
- * Take a screenshot from the current scene and return a {@link Texture}. This can applied to a surface in 3D space.
- * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.
+/**
+ * Take a screenshot from the current scene and return a {@link Texture}. This can be applied to a surface in 3D space.  
+ * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.  
  * @returns The texture of the screenshot. Returns null if the screenshot could not be taken.
+ * @category Utilities
+ * @example
+ * ```ts
+ * // Create a texture from the current view
+ * const screenshotTexture = screenshot2({ type: "texture", width: 512, height: 512 });
+ * if (screenshotTexture) {
+ *   myMaterial.map = screenshotTexture;
+ *   myMaterial.needsUpdate = true;
+ * }
+ *
+ * // Update an existing texture
+ * const existingTexture = new Texture();
+ * screenshot2({ type: "texture", target: existingTexture, transparent: true });
+ * ```
  */
 export function screenshot2(opts: ScreenshotOptionsTexture): Texture | null;
+
 /**
- * Take a screenshot from the current scene.  
- * @param opts
- * @returns The data url of the screenshot. Returns null if the screenshot could not be taken.
- * ```ts	
- * const res = screenshot2({
- *    width: 1024,
+ * Take a screenshot from the current scene and return a data URL string.
+ *
+ * @param opts Screenshot options. All properties are optional.
+ * @returns The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.
+ * @category Utilities
+ *
+ * @example Basic screenshot
+ * ```ts
+ * // Take a simple screenshot with default settings
+ * const dataUrl = screenshot2({});
+ * console.log(dataUrl); // "data:image/webp;base64,..."
+ * ```
+ *
+ * @example High-resolution screenshot with transparent background
+ * ```ts
+ * const dataUrl = screenshot2({
+ *   width: 2048,
+ *   height: 2048,
+ *   mimeType: "image/png",
+ *   transparent: true,
+ *   trim: true, // Remove transparent edges
+ * });
+ * ```
+ *
+ * @example Screenshot with custom background color
+ * ```ts
+ * import { Color } from "three";
+ *
+ * const dataUrl = screenshot2({
+ *   width: 1024,
+ *   height: 1024,
+ *   background: new Color(0x00ff00), // Green background
+ * });
+ * ```
+ *
+ * @example Download screenshot automatically
+ * ```ts
+ * screenshot2({
+ *   width: 1920,
+ *   height: 1080,
+ *   mimeType: "image/jpeg",
+ *   download_filename: "my-scene.jpg",
+ * });
+ * ```
+ *
+ * @example Manual download using saveImage
+ * ```ts
+ * const dataUrl = screenshot2({
+ *   width: 1024,
+ *   height: 1024,
+ *   mimeType: "image/webp",
+ *   transparent: true,
+ * });
+ * if (dataUrl) {
+ *   saveImage(dataUrl, "screenshot.webp");
+ * }
+ * ```
+ *
+ * @example Screenshot from specific camera
+ * ```ts
+ * const myCamera = this.gameObject.getComponent(Camera);
+ * const dataUrl = screenshot2({
+ *   camera: myCamera,
+ *   width: 1024,
  *   height: 1024,
- *  mimeType: "image/webp",
- * transparent: true,
- * })
- * // use saveImage to download the image
- * saveImage(res, "screenshot.webp");
+ * });
  * ```
  */
 export function screenshot2(opts: ScreenshotOptionsDataUrl): string | null;
 
 /**
- * Take a screenshot asynchronously from the current scene.
- * @returns A promise that resolves with the blob of the screenshot. Returns null if the screenshot could not be taken.
- * @param {ScreenshotOptionsBlob} opts Set `{ type: "blob" }` to get a blob instead of a data url.
+ * Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.  
+ *
+ * @param opts Set `{ type: "blob" }` to get a blob instead of a data url. All other {@link ScreenshotOptions} are also available.  
+ * @returns A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.  
+ * @category Utilities
+ *
+ * @example Upload screenshot to server
+ * ```ts
+ * const blob = await screenshot2({ type: "blob", mimeType: "image/png" });
+ * if (blob) {
+ *   const formData = new FormData();
+ *   formData.append("screenshot", blob, "screenshot.png");
+ *   await fetch("/api/upload", { method: "POST", body: formData });
+ * }
+ * ```
+ *
+ * @example Save blob to file (browser download)
+ * ```ts
+ * const blob = await screenshot2({
+ *   type: "blob",
+ *   width: 1920,
+ *   height: 1080,
+ *   transparent: true
+ * });
+ * if (blob) {
+ *   const url = URL.createObjectURL(blob);
+ *   saveImage(url, "screenshot.png");
+ *   URL.revokeObjectURL(url); // Clean up
+ * }
+ * ```
  */
 export function screenshot2(opts: ScreenshotOptionsBlob): Promise<Blob | null>;
+
+/**
+ * Take a screenshot and share it using the Web Share API (mobile-friendly).  
+ *
+ * **Note**: The Web Share API is only available in secure contexts (HTTPS) and may not be supported on all platforms/browsers.  
+ *
+ * @param opts Set `{ type: "share" }` to share the screenshot. Additional options like `filename`, `title`, `text`, and `url` can be provided.
+ * @returns A Promise that resolves with an object containing the blob and whether it was successfully shared.
+ * @category Utilities
+ *
+ * @example Share screenshot on mobile
+ * ```ts
+ * const result = await screenshot2({
+ *   type: "share",
+ *   filename: "my-creation.png",
+ *   title: "Check out my 3D scene!",
+ *   text: "I created this with Needle Engine",
+ *   url: "https://engine.needle.tools",
+ *   mimeType: "image/png",
+ * });
+ *
+ * if (result.shared) {
+ *   console.log("Screenshot shared successfully!");
+ * } else {
+ *   console.log("User cancelled or sharing not supported");
+ * }
+ * ```
+ *
+ * @example Share with fallback
+ * ```ts
+ * const result = await screenshot2({
+ *   type: "share",
+ *   filename: "screenshot.webp",
+ *   file_type: "image/webp",
+ * });
+ *
+ * if (!result.shared && result.blob) {
+ *   // Fallback: download the image instead
+ *   const url = URL.createObjectURL(result.blob);
+ *   saveImage(url, "screenshot.webp");
+ *   URL.revokeObjectURL(url);
+ * }
+ * ```
+ */
 export function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOptionsShareReturnType>;
+
+/**
+ * Take a screenshot from the current scene with advanced options.  
+ *
+ * This is the main screenshot function in Needle Engine with support for multiple output formats:  
+ * - **Data URL** (default): Returns a base64-encoded string suitable for img src attributes
+ * - **Texture**: Returns a Three.js Texture that can be applied to materials
+ * - **Blob**: Returns a Blob for uploading or processing (async)
+ * - **Share**: Uses the Web Share API to share the screenshot (async, mobile-friendly)
+ *
+ * @param opts Screenshot options. Use the `type` property to specify output format. See {@link ScreenshotOptions} for all available options.
+ * @returns Depending on the `type` option:
+ * - Data URL (string) when `type` is undefined or not specified
+ * - Texture when `type: "texture"`
+ * - Promise<Blob | null> when `type: "blob"`
+ * - Promise<{blob, shared}> when `type: "share"`
+ *
+ * Returns null (or Promise resolving to null) if the screenshot could not be taken.
+ *
+ * @category Utilities
+ *
+ * @example WebXR / AR Screenshots
+ * ```ts
+ * // Screenshots work automatically in WebXR sessions
+ * // The camera feed will be composited with your 3D content
+ * const dataUrl = screenshot2({
+ *   width: 1920,
+ *   height: 1080
+ * });
+ * ```
+ *
+ * **Note for AR Screenshots**: To include the device camera feed in AR screenshots, you need to request camera access.
+ * This is done automatically when you use {@link WebARCameraBackground} component in your scene.
+ * If you're not using WebARCameraBackground, you can request camera access manually:
+ * ```ts
+ * export class MyComponent extends Behaviour {
+ *   onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void {
+ *     if (mode === "immersive-ar") {
+ *       args.optionalFeatures = args.optionalFeatures || [];
+ *       args.optionalFeatures.push('camera-access');
+ *     }
+ *   }
+ * }
+ * ```
+ * Without camera access, AR screenshots will only show your 3D content without the real-world background.
+ *
+ * @example Combining multiple options
+ * ```ts
+ * // High-res transparent screenshot with custom camera
+ * const myCamera = this.gameObject.getComponent(Camera);
+ * const texture = screenshot2({
+ *   type: "texture",
+ *   camera: myCamera,
+ *   width: 2048,
+ *   height: 2048,
+ *   transparent: true,
+ *   trim: true,
+ *   render_events: true, // Ensure reflection probes are updated
+ * });
+ * ```
+ *
+ * @see {@link screenshot} for a simpler alternative with fewer options
+ * @see {@link saveImage} for downloading data URLs
+ * @see {@link ScreenshotOptions} for all available options
+ */
 export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTexture | ScreenshotOptionsBlob | ScreenshotOptionsShare)
     : Texture | string | null | Promise<Blob | null> | Promise<ScreenshotOptionsShareReturnType> {
 

package/src/engine/engine_utils_screenshot.xr.ts

@@ -5,7 +5,7 @@ import { isDevEnvironment, showBalloonError } from "./debug/index.js";
 // Adapted from WebARCameraBackground
 
 /**
- * Assigns the camera feed to a texture - this must be called during the render loop
+ * Assigns the camera feed to a texture - this must be called during the render loop.  
  */
 export function updateTextureFromXRFrame(renderer: WebGLRenderer, target: Texture): boolean {
 

package/src/engine/extensions/NEEDLE_techniques_webgl.ts

@@ -621,6 +621,9 @@ function createUniformProperties(material: CustomShader) {
                 case "_Color":
                     defineProperty("color", key);
                     break;
+                case "_map":
+                    defineProperty("map", key);
+                    break;
                 // case "_Metallic":
                 //     defineProperty("metalness", key);
                 //     break;

package/src/engine/xr/NeedleXRSession.ts

@@ -279,7 +279,12 @@ const $initialFov = Symbol("initial-fov");
  * The XRRig can be accessed via the `rig` property  
  * Set a custom XRRig via `NeedleXRSession.addRig(...)` or `NeedleXRSession.removeRig(...)`  
  * By default the active XRRig with the highest priority in the scene is used
+ *
+ * ### Screenshots in XR
+ * Screenshots work automatically during XR sessions, including AR camera feed compositing. See {@link screenshot2} for more information.
+ *
  * @category XR
+ * @see {@link screenshot2} for taking screenshots in XR sessions
  */
 export class NeedleXRSession implements INeedleXRSession {
 

package/src/engine-components/ContactShadows.ts

@@ -13,6 +13,9 @@ import { HideFlags, IGameObject, Vec3 } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js"
 import { setCustomVisibility } from "../engine/js-extensions/Layers.js";
 import { Behaviour, GameObject } from "./Component.js";
+import type { Light } from "./Light.js";
+import type { Renderer } from "./Renderer.js";
+import type { ShadowCatcher } from "./ShadowCatcher.js";
 
 const debug = getParam("debugcontactshadows");
 
@@ -45,7 +48,8 @@ type FitParameters = {
 
 /**
  * [ContactShadows](https://engine.needle.tools/docs/api/ContactShadows) renders proximity-based soft shadows on flat surfaces.
- * Ideal for products or objects that need visual grounding without real-time shadows.    
+ * Ideal for products or objects that need visual grounding without real-time shadows.  
+ * Produces soft, blurred shadows that hug the ground, giving a sense of contact and depth.     
  * 
  * ![](https://cloud.needle.tools/-/media/87bPTNXHcsbV-An-oSEvHQ.gif)
  *
@@ -72,6 +76,7 @@ type FitParameters = {
  * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
+ * @see {@link ShadowCatcher} for real-time shadows from lights (more accurate, higher performance cost)
  * @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

package/src/engine-components/EventList.ts

@@ -175,10 +175,10 @@ export class EventList<TArgs extends any = any> implements IEventList {
                         // remap the arguments to the new instance (e.g. if an object is passed as an argument to the event list and this object has been cloned we want to remap it to the clone)
                         const newArguments = method.arguments?.map(arg => {
                             if (arg instanceof Object && arg.uuid) {
-                                return ctx[arg.uuid];
+                                return ctx[arg.uuid].clone;
                             }
                             else if ((arg as IComponent)?.isComponent) {
-                                return ctx[(arg as IComponent).guid];
+                                return ctx[(arg as IComponent).guid].clone;
                             }
                             return arg;
                         });

package/src/engine-components/Renderer.ts

@@ -200,22 +200,24 @@ class SharedMaterialArray implements ISharedMaterials {
 }
 
 /**
- * [Renderer](https://engine.needle.tools/docs/api/Renderer) controls rendering properties of meshes including materials,
- * lightmaps, reflection probes, and GPU instancing.
+ * 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.
+ * **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.
+ * **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.
+ * **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:**
+ * **Debug options:**  
  * - `?debugrenderer` - Log renderer info
  * - `?wireframe` - Show wireframe rendering
  * - `?noinstancing` - Disable GPU instancing
@@ -235,7 +237,6 @@ class SharedMaterialArray implements ISharedMaterials {
  * @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 {
 

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/ScreenCapture.ts

@@ -100,6 +100,7 @@ export declare type ScreenCaptureOptions = {
  *
  * @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

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 {