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

package/src/engine-components/DropListener.ts

@@ -1,9 +1,9 @@
 import { Box3, Object3D, Vector2, Vector3 } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
+import type { AssetReference } from "../engine/engine_addressables.js"
 import { AnimationUtils } from "../engine/engine_animation.js";
 import { Context } from "../engine/engine_context.js";
-import { destroy } from "../engine/engine_gameobject.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { getLoader } from "../engine/engine_gltf.js";
 import { BlobStorage } from "../engine/engine_networking_blob.js";
@@ -109,40 +109,52 @@ class DropListenerAddedEvent<T extends DropListenerOnDropArguments> extends Cust
  */
 const blobKeyName = "blob";
 
-/** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene  
- * It can be used to allow users to drag and drop glTF files into the scene to add new objects.  
- * Existing child objects will behave like placeholders and will be removed when new files are dropped.  
- * 
- * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
- * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
- * 
- * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
- * 
- * The following events are dispatched by the DropListener:
- * - **object-added** - dispatched when a new object is added to the scene
- * - **file-dropped** - dispatched when a file is dropped into the scene
- * 
- * @example
- * ```typescript
- * import { DropListener, DropListenerEvents } from "@needle-tools/engine";
- * 
- * const dropListener = new DropListener();
- * 
- * gameObject.addComponent(dropListener);
- * dropListener.on(DropListenerEvents.FileDropped, (evt) => {
- *   console.log("File dropped", evt.detail);
- *   const file = evt.detail as File;
- * });
+/**
+ * DropListener enables drag-and-drop loading of 3D files directly into your scene.  
+ * Users can drop glTF/GLB files onto the canvas to dynamically add new objects at runtime.   
  * 
+ * [![](https://cloud.needle.tools/-/media/p5LNPTQ0u4mRXA6WiSmzIQ.gif)](https://engine.needle.tools/samples/droplistener)  
+ *
+ * **Supported formats:** glTF, GLB, FBX, OBJ, USDZ, VRM  
+ *
+ * **Key features:**  
+ * - Drop files directly onto canvas or onto a specific {@link dropArea}
+ * - Paste URLs from clipboard (Ctrl/Cmd+V)
+ * - Auto-fit objects to a specific size with {@link fitIntoVolume}
+ * - Network sync to share dropped objects with other users
+ * - Special handling for GitHub and Polyhaven URLs
+ *
+ * **Events:**  
+ * - `file-dropped` - Fired for each dropped file
+ * - `object-added` - Fired when object is loaded and added to scene
+ *
+ * **Debug:** Use `?debugdroplistener` URL parameter
+ *
+ * @example Listen for dropped objects
+ * ```ts
+ * const dropListener = myObject.addComponent(DropListener);
+ * dropListener.useNetworking = true;
+ * dropListener.fitIntoVolume = true;
+ *
  * dropListener.on(DropListenerEvents.ObjectAdded, (evt) => {
- *    console.log("Object added", evt.detail);
- *    const gltf = evt.detail as GLTF;
+ *   const { object, model } = evt.detail;
+ *   console.log("Added:", object.name);
  * });
  * ```
- * 
- * @summary Component to handle drag and drop of files into the scene
+ *
+ * @example Load from URL programmatically  
+ * ```ts
+ * const obj = await dropListener.loadFromURL("https://example.com/model.glb");
+ * ```  
+ * Hint: We recommend to use {@link AssetReference} for preloading and referencing assets in code if you simply want to load a model.
+ *
+ * @summary Drag-and-drop file loading for 3D assets
  * @category Asset Management
  * @group Components
+ * @see {@link SceneSwitcher} for loading entire scenes
+ * @see {@link AssetReference} for preloading assets
+ * @see {@link SyncedTransform} for networking support
+ * @link https://engine.needle.tools/samples/droplistener for a live demo
  */
 export class DropListener extends Behaviour {
 

package/src/engine-components/Duplicatable.ts

@@ -12,26 +12,57 @@ import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.
 import { ObjectRaycaster } from "./ui/Raycaster.js";
 
 /**
- * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.   
- *  
+ * The [Duplicatable](https://engine.needle.tools/docs/api/Duplicatable) component creates clones of a GameObject when clicked/tapped/dragged.
+ * Perfect for spawning objects, creating drag-and-drop inventories, or multiplayer object creation.   
+ * 
+ * ![](https://cloud.needle.tools/-/media/J_ij9vxhh1zhS8h2ftGBXQ.gif)
+ *
+ * **How it works:**
+ * - When the user clicks on this object, it creates a clone of the assigned `object`  
+ * - The clone is automatically set up with {@link DragControls} so users can drag it   
+ * - If networking is enabled, clones are synced via {@link SyncedTransform}  
+ * - Rate limiting prevents spam (controlled by `limitCount`)  
+ *
+ * **Setup tips:**  
+ * - Assign `object` to a template object (it will be hidden and used as source)  
+ * - If `object` is not assigned, the component's own GameObject is used as template  
+ * - Add an {@link ObjectRaycaster} to enable pointer detection (added automatically if missing)  
+ *
+ * @example Basic duplicatable button
+ * ```ts
+ * const duplicatable = spawnButton.addComponent(Duplicatable);
+ * duplicatable.object = templateObject; // Object to clone
+ * duplicatable.parent = spawnContainer;  // Where to place clones
+ * duplicatable.limitCount = 10;          // Max 10 per second
+ * ```
+ *
  * @summary Duplicates a GameObject on pointer events
  * @category Interactivity
  * @group Components
+ * @see {@link DragControls} for dragging the duplicated objects
+ * @see {@link SyncedTransform} for networking support
+ * @see {@link GameObject.instantiateSynced} for the underlying instantiation
+ * @link https://engine.needle.tools/samples/collaborative-sandbox/
  */
 export class Duplicatable extends Behaviour implements IPointerEventHandler {
 
-    /** Duplicates will be parented into the set object. If not defined, this GameObject will be used as parent. */
+    /**
+     * Parent object for spawned duplicates.
+     * If not set, duplicates are parented to this GameObject's parent.
+     */
     @serializable(Object3D)
     parent: GameObject | null = null;
 
-    /** The object to be duplicated. If no object is assigned then the object the Duplicatable component is attached to will be used for cloning.
-     * @default null
+    /**
+     * Template object to duplicate. This object will be hidden and used as the source for clones.
+     * If not assigned, this GameObject itself is used as the template.
      */
     @serializable(Object3D)
     object: GameObject | null = null;
 
     /**
-     * The maximum number of objects that can be duplicated in the interval.
+     * Maximum duplications allowed per second to prevent spam.
+     * The counter decreases by 1 each second.
      * @default 60
      */
     @serializable()

package/src/engine-components/EventList.ts

@@ -4,6 +4,9 @@ import type { IComponent, IEventList } from "../engine/engine_types.js";
 
 const argumentsBuffer = new Array<any>();
 
+/**
+ * CallInfo represents a single callback method that can be invoked by the {@link EventList}.  
+ */
 export class CallInfo {
     /**
      * When the CallInfo is enabled it will be invoked when the EventList is invoked
@@ -101,24 +104,49 @@ export class EventListEvent<TArgs extends any> extends Event { //implements Arra
 
 
 /**
- * The EventList is a class that can be used to create a list of event listeners that can be invoked.  
- * 
- * @example
- * ```ts
- * // create an event list
- * const onClick = new EventList<(event: MouseEvent) => void>();
+ * EventList manages a list of callbacks that can be invoked together.  
+ * Used for Unity-style events that can be configured in the editor (Unity or Blender).  
+ *
+ * **Serialization:**  
+ * EventLists are serializable - callbacks configured in Unity/Blender will work at runtime.  
+ * Mark fields with `@serializable(EventList)` for editor support.  
+ *
+ * **Usage patterns:**  
+ * - Button click handlers
+ * - Animation events
+ * - Custom component callbacks
+ * - Scene loading events  
  * 
- * // add an event listener
- * onClick.addEventListener((event) => {
- *   console.log("Clicked!", event);
- * });
+ * ![](https://cloud.needle.tools/-/media/P7bEKQvfgRUMTb2Wi1hWXg.png)  
+ * *Screenshot of a Unity component with an EventList field*  
  * 
- * // invoke the event list
- * onClick.invoke(new MouseEvent("click"));
+ * ![](https://cloud.needle.tools/-/media/i2hi2OHfbaDyHyBL6Gt58A.png)  
+ * *Screenshot of a Blender component with an EventList field*
+ *
+ * @example Create and use an EventList
+ * ```ts
+ * // Define in your component
+ * @serializable(EventList)
+ * onClick: EventList = new EventList();
+ *
+ * // Add listeners
+ * this.onClick.addEventListener(() => console.log("Clicked!"));
+ *
+ * // Invoke all listeners
+ * this.onClick.invoke();
  * ```
- * 
+ *
+ * @example Listen with arguments
+ * ```ts
+ * const onScore = new EventList<{ points: number }>();
+ * onScore.addEventListener(data => console.log("Scored:", data.points));
+ * onScore.invoke({ points: 100 });
+ * ```
+ *
  * @category Events
  * @group Utilities
+ * @see {@link CallInfo} for individual callback configuration
+ * @see {@link Button} for UI button events
  */
 export class EventList<TArgs extends any = any> implements IEventList {
 
@@ -147,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/EventTrigger.ts

@@ -12,7 +12,7 @@ class TriggerEvent {
 }
 
 /**
- * The EventTrigger component is used to trigger events when certain pointer events occur on the GameObject.
+ * The [EventTrigger](https://engine.needle.tools/docs/api/EventTrigger) component is used to trigger events when certain pointer events occur on the GameObject.
  * It implements the {@link IPointerEventHandler} interface and can be used to expose events to the user in the editor without writing code.
  * 
  * @summary Triggers events on pointer interactions

package/src/engine-components/Fog.ts

@@ -4,15 +4,37 @@ import { serializable } from "../engine/engine_serialization.js";
 import { Behaviour } from "./Component.js";
 
 
+/**
+ * Fog rendering mode
+ */
 enum FogMode {
+    /** Linear fog increases uniformly with distance */
     Linear = 1,
+    /** Exponential fog increases exponentially with distance */
     Exponential = 2,
+    /** Exponential squared fog for denser falloff */
     ExponentialSquared = 3,
 }
 
-/** @internal */
+/**
+ * Adds distance-based fog effect to the scene.  
+ * When enabled, objects will fade into the fog color based on their distance from the camera.    
+ * 
+ * This component is automatically added to the scene when fog is enabled in the editor.   
+ * For setting fog from code you can simply use `scene.fog = new Fog3(color, near, far)` without adding this component.
+ *
+ * @summary Adds fog effect to the scene
+ * @category Rendering
+ * @group Components
+ * @link https://threejs.org/docs/#Fog
+ */
 export class Fog extends Behaviour {
 
+    /**
+     * The underlying Three.js Fog object. You can modify its properties directly for more advanced control.
+     * @remarks The Fog component provides convenient access to common fog properties like `near`, `far`, and `color`. Modifying those will update the underlying `fog` object accordingly. However, you can also access and modify the `fog` object directly for more advanced use cases, such as changing the fog mode or using a custom shader.  
+     * @link https://threejs.org/docs/#Fog for available properties and methods on the Fog object.
+     */
     get fog() {
         if (!this._fog) this._fog = new Fog3(0x000000, 0, 50);
         return this._fog;

package/src/engine-components/GridHelper.ts

@@ -5,11 +5,27 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * GridHelper is a component that allows to display a grid in the scene.
+ * The [GridHelper](https://engine.needle.tools/docs/api/GridHelper) displays a flat grid in the scene for visual reference.
+ * Useful for debugging, level design, or providing spatial context.  
  * 
- * @example Display a grid in the scene
+ * ![](https://cloud.needle.tools/-/media/prWArU8xTbgBKWQOvhTOag.gif)
+ *
+ * **Properties:**  
+ * - `color0` / `color1` - Alternating grid line colors
+ * - `isGizmo` - When true, only shows when gizmos are enabled
+ *
+ * @example Add a grid to the scene
+ * ```ts
+ * const grid = myObject.addComponent(GridHelper);
+ * grid.color0 = new Color(0.3, 0.3, 0.3);
+ * grid.color1 = new Color(0.5, 0.5, 0.5);
+ * ```  
+ *
  * @category Helpers
  * @group Components
+ * @see {@link Gizmos} for debug visualization
+ * 
+ * ![](https://cloud.needle.tools/-/media/i5KGKBUQ3iAX9h6o_9EY2w.jpg)
  */
 export class GridHelper extends Behaviour {
 

package/src/engine-components/GroundProjection.ts

@@ -10,13 +10,35 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debuggroundprojection");
 
 /**
- * GroundProjectedEnv creates a ground projection of the current environment map.    
- * 
- * - Example https://engine.needle.tools/samples/ground-projection
+ * The [GroundProjectedEnv](https://engine.needle.tools/docs/api/GroundProjectedEnv) projects the environment map onto a virtual ground plane.
+ * Creates a realistic floor from 360° panoramas/HDRIs by deforming the skybox
+ * into a hemisphere with a beveled floor.  
+ *  
  * 
+ * [![](https://cloud.needle.tools/-/media/8LDMd4TnGxVIj1XOfxIUIA.gif)](https://engine.needle.tools/samples/ground-projection)
+ *
+ * **Key properties:**  
+ * - `radius` - Size of the projection sphere (keep camera inside)
+ * - `height` - How high the original photo was taken (affects floor magnification)
+ * - `autoFit` - Automatically center and position at ground level
+ * - `arBlending` - Blend with real-world in AR (0=hidden, 1=visible)
+ *
+ * **Debug:** Use `?debuggroundprojection` URL parameter.  
+ *
+ * @example Apply ground projection
+ * ```ts
+ * const ground = myObject.getComponent(GroundProjectedEnv);
+ * ground.radius = 100;
+ * ground.height = 2;
+ * ground.apply();
+ * ```
+ *
  * @summary Projects the environment map onto the ground
  * @category Rendering
  * @group Components
+ * @see {@link Camera} for environment/skybox settings
+ * @see {@link ContactShadows} for ground shadows
+ * @link https://engine.needle.tools/samples/ground-projection for a demo of ground projection
  */
 export class GroundProjectedEnv extends Behaviour {
 

package/src/engine-components/Interactable.ts

@@ -1,8 +1,23 @@
 import { Behaviour } from "./Component.js";
 
 /**
- * Marks an object as currently being interacted with.
- * For example, DragControls set this on the dragged object to prevent DeleteBox from deleting it.
+ * UsageMarker indicates an object is currently being interacted with.  
+ * Components like {@link DragControls} add this to prevent accidental deletion  
+ * by {@link DeleteBox} while the user is dragging. 
+ *
+ * @example Check if object is in use
+ * ```ts
+ * const marker = object.getComponent(UsageMarker);
+ * if (marker?.isUsed) {
+ *   console.log("Object is being used by:", marker.usedBy);
+ * }
+ * ```
+ *
+ * @summary Marks object as currently being interacted with
+ * @category Interactivity
+ * @group Components
+ * @see {@link DeleteBox} respects this marker
+ * @see {@link DragControls} adds this during drag
  */
 export class UsageMarker extends Behaviour
 {

package/src/engine-components/Joints.ts

@@ -5,12 +5,22 @@ import { Behaviour } from "./Component.js";
 import { Rigidbody } from "./RigidBody.js";
 
 /**
- * Base class for physics joints connecting two rigid bodies.
- * @summary Connect two Rigidbodies
+ * Base class for physics joints that connect two {@link Rigidbody} components.
+ * Joints constrain how two bodies can move relative to each other.
+ *
+ * The joint is created between:
+ * - The {@link Rigidbody} on this GameObject (automatically found)
+ * - The {@link connectedBody} Rigidbody you specify
+ *
+ * @summary Connect two Rigidbodies with physics constraints
  * @category Physics
  * @group Components
+ * @see {@link FixedJoint} for rigid connections
+ * @see {@link HingeJoint} for rotating connections
+ * @see {@link Rigidbody} for physics bodies
  */
 export abstract class Joint extends Behaviour {
+    /** The other Rigidbody to connect to */
     @serializable(Rigidbody)
     connectedBody?: Rigidbody;
 
@@ -37,10 +47,25 @@ export abstract class Joint extends Behaviour {
 }
 
 /**
- * The FixedJoint groups together 2 rigidbodies, making them stick together in their bound position
- * @summary Connect two Rigidbodies and make them stick together
+ * FixedJoint locks two {@link Rigidbody} components together, making them move as one rigid unit.
+ * The bodies maintain their relative position and rotation at the time the joint is created.
+ *
+ * Use this for:
+ * - Attaching objects together permanently
+ * - Creating compound rigid bodies
+ * - Welding broken pieces back together
+ *
+ * @example Attach a weapon to a character
+ * ```ts
+ * const joint = weapon.addComponent(FixedJoint);
+ * joint.connectedBody = characterRigidbody;
+ * ```
+ *
+ * @summary Lock two Rigidbodies together rigidly
  * @category Physics
  * @group Components
+ * @see {@link Joint} base class
+ * @see {@link HingeJoint} for rotating connections
  */
 export class FixedJoint extends Joint {
 
@@ -50,18 +75,36 @@ export class FixedJoint extends Joint {
 }
 
 /**
- * The HingeJoint groups together 2 rigid bodies, constraining them to move like connected by a hinge.
- * 
- * You can specify the anchor point and axis of rotation for the hinge.
- * @summary Connect two Rigidbodies with a hinge
+ * HingeJoint connects two {@link Rigidbody} components with a rotating constraint,
+ * like a door hinge or wheel axle. Bodies can only rotate around the specified axis.
+ *
+ * Use this for:
+ * - Doors and gates
+ * - Wheels and axles
+ * - Pendulums
+ * - Any rotating mechanical connection
+ *
+ * @example Create a door hinge
+ * ```ts
+ * const hinge = door.addComponent(HingeJoint);
+ * hinge.connectedBody = doorFrameRigidbody;
+ * hinge.anchor = new Vector3(0, 0, 0); // Hinge position
+ * hinge.axis = new Vector3(0, 1, 0);   // Rotate around Y axis
+ * ```
+ *
+ * @summary Connect two Rigidbodies with a rotating hinge
  * @category Physics
  * @group Components
+ * @see {@link Joint} base class
+ * @see {@link FixedJoint} for rigid connections
  */
 export class HingeJoint extends Joint {
 
+    /** Local position of the hinge pivot point */
     @serializable(Vector3)
     anchor?: Vector3;
 
+    /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
     @serializable(Vector3)
     axis?: Vector3;
 

package/src/engine-components/LODGroup.ts

@@ -8,17 +8,32 @@ import { Renderer } from "./Renderer.js";
 const debug = getParam("debuglods");
 const noLods = getParam("nolods");
 
+/**
+ * Defines how LOD levels transition between each other
+ */
 enum LODFadeMode {
+    /** Instant switch between LOD levels */
     None = 0,
+    /** Smooth cross-fade transition between levels */
     CrossFade = 1,
+    /** SpeedTree-style blending for vegetation */
     SpeedTree = 2,
 }
 
+/**
+ * Defines a single LOD level with its transition distance and associated renderers.
+ * Used by {@link LODGroup} to configure level of detail switching.
+ */
 export class LODModel {
+    /** Screen height ratio (0-1) at which this LOD becomes active */
     @serializable()
     screenRelativeTransitionHeight!: number;
+
+    /** Distance from camera at which this LOD becomes active */
     @serializable()
     distance!: number;
+
+    /** Renderers to show at this LOD level */
     @serializable(Renderer)
     renderers!: Renderer[];
 }
@@ -39,23 +54,36 @@ declare class LODSetting {
 }
 
 /**
- * LODGroup allows to create a group of LOD levels for an object.
- * 
+ * LODGroup manages multiple levels of detail for optimized rendering.  
+ * Objects switch between different detail levels based on distance from camera.  
+ *
+ * LOD levels are defined in {@link LODModel} objects, each specifying:
+ * - The distance at which that level becomes active
+ * - The {@link Renderer} components to show at that level
+ *
+ * This is useful for performance optimization - showing high-detail models up close  
+ * and lower-detail versions at distance where the difference isn't visible.  
+ *
+ * **Progressive Loading:**  
+ * For automatic texture/mesh LOD streaming, see the `@needle-tools/gltf-progressive` package  
+ * which provides progressive loading capabilities independent of this component.
+ *
+ * **Debug options:**
+ * - `?debuglods` - Log LOD switching information
+ * - `?nolods` - Disable LOD system entirely
+ *
  * @summary Level of Detail Group for optimizing rendering
  * @category Rendering
  * @group Components
+ * @see {@link LODModel} for configuring individual LOD levels
+ * @see {@link Renderer} for the renderers controlled by LOD
+ * @see {@link LODsManager} for programmatic control of progressive LODs
+ * @link https://npmjs.com/package/@needle-tools/gltf-progressive
  */
 export class LODGroup extends Behaviour {
-
-    fadeMode: LODFadeMode = LODFadeMode.None;
-    @serializable(Vector3)
-    localReferencePoint: Vector3 | undefined = undefined;
-    lodCount: number = 0;
-    size: number = 0;
-    animateCrossFading: boolean = false;
-
+    /** Array of LOD level configurations */
     @serializable(LODModel)
-    lodModels?: LODModel[];
+    readonly lodModels: LODModel[] = []
 
     private _lods: LOD[] = [];
     private _settings: LODSetting[] = [];
@@ -145,6 +173,12 @@ export class LODGroup extends Behaviour {
 
     private _distanceFactor = 1;
 
+    /**
+     * Adjusts all LOD transition distances by a multiplier.
+     * Values > 1 push LOD transitions further away (higher quality at distance).
+     * Values < 1 bring transitions closer (better performance).
+     * @param factor Multiplier to apply to all LOD distances
+     */
     distanceFactor(factor: number) {
         if (factor === this._distanceFactor) return;
         this._distanceFactor = factor;

package/src/engine-components/Light.ts

@@ -1,14 +1,11 @@
 import { CameraHelper, Color, DirectionalLight, DirectionalLightHelper, Light as ThreeLight, OrthographicCamera, PointLight, SpotLight, Vector3 } from "three";
-import { get } from "three-mesh-ui/build/types/core/DefaultValues.js";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { FrameEvent } from "../engine/engine_setup.js";
 import { setWorldPositionXYZ } from "../engine/engine_three_utils.js";
 import type { ILight } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js";
-import { type NeedleXREventArgs } from "../engine/xr/api.js";
 import { Behaviour, GameObject } from "./Component.js";
-import { WebARSessionRoot } from "./webxr/WebARSessionRoot.js";
 
 // https://threejs.org/examples/webgl_shadowmap_csm.html
 
@@ -26,7 +23,8 @@ const debug = getParam("debuglights");
 
 
 /**
- * Defines the type of light in a scene.
+ * Defines the type of light in a scene.  
+ * @see {@link Light} for configuring light properties and behavior
  */
 export enum LightType {
     /** Spot light that emits light in a cone shape */
@@ -44,7 +42,8 @@ export enum LightType {
 }
 
 /**
- * Defines how a light contributes to the scene lighting.
+ * Defines how a light contributes to the scene lighting.  
+ * @see {@link Light} for configuring light properties and behavior
  */
 export enum LightmapBakeType {
     /** Light affects the scene in real-time with no baking */
@@ -58,6 +57,7 @@ export enum LightmapBakeType {
 /**
  * Defines the shadow casting options for a Light.
  * @enum {number}
+ * @see {@link Light} for configuring shadow settings
  */
 enum LightShadows {
     /** No shadows are cast */
@@ -68,17 +68,39 @@ enum LightShadows {
     Soft = 2,
 }
 
-/** 
- * The Light component creates a light source in the scene.
- * Supports directional, spot, and point light types with various customization options.
- * Lights can cast shadows with configurable settings and can be set to baked or realtime rendering.
- * 
- * Debug mode can be enabled with the URL parameter `?debuglights`, which shows
- * additional console output and visual helpers for lights.
- * 
+/**
+ * [Light](https://engine.needle.tools/docs/api/Light) creates a light source in the scene for illuminating 3D objects.
+ *
+ * **Light types:**
+ * - `Directional` - Sun-like parallel rays (best for outdoor scenes)
+ * - `Point` - Omnidirectional from a point (bulbs, candles)
+ * - `Spot` - Cone-shaped (flashlights, stage lights)
+ *
+ * **Shadows:**
+ * Enable shadows via `shadows` property. Configure quality with shadow resolution
+ * settings. Directional lights support adaptive shadow cascades.
+ *
+ * **Performance tips:**
+ * - Use baked lighting (`lightmapBakeType = Baked`) when possible
+ * - Limit shadow-casting lights (1-2 recommended)
+ * - Reduce shadow resolution for mobile
+ *
+ * **Debug:** Use `?debuglights` URL parameter for visual helpers.
+ *
+ * @example Configure a directional light
+ * ```ts
+ * const light = myLight.getComponent(Light);
+ * light.intensity = 1.5;
+ * light.color = new Color(1, 0.95, 0.9); // Warm white
+ * light.shadows = LightShadows.Soft;
+ * ```
+ *
  * @summary Light component for various light types and shadow settings
  * @category Rendering
  * @group Components
+ * @see {@link LightType} for available light types
+ * @see {@link ReflectionProbe} for environment reflections
+ * @see {@link Camera} for rendering configuration
  */
 export class Light extends Behaviour implements ILight {