@needle-tools/engine 4.13.0 → 4.13.1

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

@@ -10,6 +10,8 @@ import { Behaviour } from "./Component.js";
 import { IUSDExporterExtension } from "./export/usdz/Extension.js";
 import { USDZExporter } from "./export/usdz/USDZExporter.js";
 import { Renderer } from "./Renderer.js";
+import type { Camera } from "./Camera.js";
+import type { OrbitControls } from "./OrbitControls.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 {
 

package/src/engine-components/ShadowCatcher.ts

@@ -4,6 +4,9 @@ import { ObjectUtils, PrimitiveType } from "../engine/engine_create_objects.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { RGBAColor } from "../engine/js-extensions/index.js";
 import { Behaviour } from "./Component.js";
+import type { ContactShadows } from "./ContactShadows.js";
+import type { Light } from "./Light.js";
+import type { Renderer } from "./Renderer.js";
 
 /**
  * The mode of the ShadowCatcher.  
@@ -18,14 +21,66 @@ enum ShadowMode {
 }
 
 /**
- * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.    
- * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.  
- * 
- * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
- * 
- * @summary Creates a shadow mask or a light occluder 
+ * ShadowCatcher renders real-time shadows cast by lights onto a mesh surface.  
+ * Captures actual shadow data from the scene's lighting system (directional lights, point lights, spot lights).  
+ *
+ * If the GameObject is a Mesh, it applies a shadow-catching material to it.  
+ * Otherwise, it creates a quad mesh with the shadow-catching material automatically.  
+ *
+ * [![](https://cloud.needle.tools/-/media/pFXPchA4vynNKOjgG_KucQ.gif)](https://engine.needle.tools/samples/shadow-catcher/)   
+ * *Additive ShadowCatcher mode with point light shadows*  
+ *
+ * [![](https://cloud.needle.tools/-/media/oIWgEU49rEA0xJ2TrbzVlg.gif)](https://engine.needle.tools/samples/transmission/)   
+ * *ShadowCatcher with directional light shadows*
+ *
+ * **Shadow Modes:**  
+ * - `ShadowMask` - Only renders shadows (works best with directional lights)  
+ * - `Additive` - Renders light additively (works best with point/spot lights)
+ * - `Occluder` - Occludes light without rendering shadows
+ *
+ * **ShadowCatcher vs ContactShadows:**
+ * - **ShadowCatcher**: Real-time shadows from actual lights. Accurate directional shadows that match light sources. Requires lights with shadows enabled. Updates every frame.
+ * - **{@link ContactShadows}**: Proximity-based ambient occlusion-style shadows. Extremely soft and diffuse, ideal for subtle grounding. Better performance, works without lights.
+ *
+ * **When to use ShadowCatcher:**
+ * - You need accurate shadows that match specific light directions
+ * - Scene has real-time lighting with shadow-casting lights
+ * - Shadows need to follow light attenuation and angles
+ * - AR/VR scenarios where light estimation is available
+ * - Hard or semi-hard shadow edges are desired
+ *
+ * **When to use ContactShadows instead:**
+ * - You want very soft, ambient occlusion-style ground shadows
+ * - Performance is critical (no per-frame shadow rendering)
+ * - Scene doesn't have shadow-casting lights
+ * - Product visualization or configurators (subtle grounding effect)
+ * - Soft, diffuse shadows are more visually appealing than accurate ones
+ *
+ * **Note:** ShadowCatcher meshes are not raycastable by default (layer 2). Change layers in `onEnable()` if raycasting is needed.
+ *
+ * @example Basic shadow catcher plane
+ * ```ts
+ * const plane = new Object3D();
+ * const catcher = addComponent(plane, ShadowCatcher);
+ * catcher.mode = ShadowMode.ShadowMask;
+ * catcher.shadowColor = new RGBAColor(0, 0, 0, 0.8);
+ * ```
+ *
+ * @example Apply to existing mesh
+ * ```ts
+ * const mesh = this.gameObject.getComponent(Mesh);
+ * const catcher = addComponent(mesh, ShadowCatcher);
+ * // The mesh will now catch shadows from scene lights
+ * ```
+ *
+ * @summary Renders real-time shadows from lights onto surfaces
  * @category Rendering
  * @group Components
+ * @see {@link ContactShadows} for proximity-based fake shadows (better performance)
+ * @see {@link Light} for shadow-casting light configuration
+ * @see {@link Renderer} for shadow receiving settings
+ * @link https://engine.needle.tools/samples/shadow-catcher/
+ * @link https://engine.needle.tools/samples/transmission/
  */
 export class ShadowCatcher extends Behaviour {
 

package/src/engine-components/Skybox.ts

@@ -114,20 +114,52 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 
 
 /**
- * RemoteSkybox is a component that allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.  
- * It supports .hdr, .exr, .jpg, .png files.
- * 
+ * The [RemoteSkybox](https://engine.needle.tools/docs/api/RemoteSkybox) component allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.
+ * It supports .hdr, .exr, .jpg, .png, and .ktx2 files.
+ *
+ * **HTML Attributes:**
+ * You can control skybox and environment from HTML using `<needle-engine>` attributes:
+ * - `background-image`: Sets the scene background/skybox image
+ * - `environment-image`: Sets the scene environment map (for reflections and lighting)
+ *
+ * These attributes accept URLs or magic skybox names (see examples below).
+ *
+ * **Magic Skybox Names:**
+ * Built-in optimized skyboxes hosted on Needle CDN:
+ * - `"studio"` - Neutral studio lighting (default)
+ * - `"blurred-skybox"` - Blurred environment
+ * - `"quicklook"` - Apple QuickLook object mode style
+ * - `"quicklook-ar"` - Apple QuickLook AR mode style
+ *
  * ### Events
  * - `dropped-unknown-url`: Emitted when a file is dropped on the scene. The event detail contains the sender, the url and a function to apply the url.
- * 
- * @example adding a skybox
+ *
+ * @example Using HTML attributes
+ * ```html
+ * <needle-engine
+ *   background-image="https://example.com/skybox.hdr"
+ *   environment-image="studio">
+ * </needle-engine>
+ * ```
+ *
+ * @example Using magic skybox names
+ * ```html
+ * <needle-engine background-image="studio"></needle-engine>
+ * <needle-engine environment-image="quicklook"></needle-engine>
+ * ```
+ *
+ * @example Adding via code
  * ```ts
- * GameObject.addComponent(gameObject, Skybox, { url: "https://example.com/skybox.hdr", background: true, environment: true });
+ * GameObject.addComponent(gameObject, RemoteSkybox, {
+ *   url: "https://example.com/skybox.hdr",
+ *   background: true,
+ *   environment: true
+ * });
  * ```
- * 
- * @example handle custom url
+ *
+ * @example Handle custom dropped URL
  * ```ts
- * const skybox = GameObject.addComponent(gameObject, Skybox);
+ * const skybox = GameObject.addComponent(gameObject, RemoteSkybox);
  * skybox.addEventListener("dropped-unknown-url", (evt) => {
  *    let url = evt.detail.url;
  *    console.log("User dropped file", url);
@@ -137,15 +169,19 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  *    evt.detail.apply(url);
  * });
  * ```
- * 
- * @example update skybox url
+ *
+ * @example Update skybox at runtime
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
+ * // Or use a magic name:
+ * skybox.setSkybox("studio");
  * ```
- * 
+ *
  * @summary Sets the skybox or environment texture of a scene
  * @category Rendering
  * @group Components
+ * @see {@link Camera} for clearFlags and background control
+ * @link https://engine.needle.tools/docs/html.html#needle-engine-element
  */
 export class RemoteSkybox extends Behaviour {