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

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 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 {
 

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.
+ * 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
+ * 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

@@ -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 component 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 {
 

package/src/engine-components/LookAtConstraint.ts

@@ -3,35 +3,53 @@ import { Object3D, Vector3 } from "three";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
 import type { OrbitControls } from "./OrbitControls.js";
+import type { LookAt } from "./api.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
+ * 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 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 {