@needle-tools/engine 4.13.0 → 4.13.1

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 {
 

package/src/engine-components/LookAtConstraint.ts

@@ -1,37 +1,55 @@
 import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
+import type { LookAt } from "./api.js";
 import { Behaviour } from "./Component.js";
 import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
- * This component is used by {@link OrbitControls} internally.
- * 
- * @summary Look At Constraint for OrbitControls
+ * The [LookAtConstraint](https://engine.needle.tools/docs/api/LookAtConstraint) component is primarely used by {@link OrbitControls} to set the camera's focus point.
+ * It does not have its own logic to update the look-at position.  
+ *
+ * The constraint uses a list of source objects - the look-at target is  
+ * calculated from the first source in the `sources` array.  
+ *
+ * **Integration with OrbitControls:**  
+ * When attached to the same GameObject as OrbitControls, this constraint  
+ * controls where the camera orbits around and looks at.  
+ *
+ * @summary Look At Constraint for camera targeting
  * @category Camera and Controls
  * @group Components
+ * @see {@link OrbitControls} for camera orbit controls
+ * @see {@link SmoothFollow} for smooth position/rotation following
+ * @see {@link LookAt} for directly making an object look at a target without using a constraint
  */
 export class LookAtConstraint extends Behaviour {
 
     /**
-     * When true the constraint is active.
+     * When true, the constraint is active and affects the target.
+     * Set to false to temporarily disable without removing sources.
      */
     @serializable()
     constraintActive: boolean = true;
+
     /**
-     * When true the look at is locked to the position of the assigned sources.
+     * When true, the look-at position is locked and won't update
+     * even if source objects move.
      */
     @serializable()
     locked: boolean = false;
+
     /**
-     * The sources to look at.
+     * Objects to look at. The first object in the array is used
+     * as the primary look-at target.
      */
     @serializable(Object3D)
     sources: Object3D[] = [];
 
     /**
-     * Set the position of the constraint.
+     * Sets the world position that the constraint should look at.
+     * Updates the first source object's position.
+     * @param worldPosition The world-space position to look at
      */
     setConstraintPosition(worldPosition: Vector3) {
         const source = this.sources[0];

package/src/engine-components/NeedleMenu.ts

@@ -3,16 +3,38 @@ import { serializable } from '../engine/engine_serialization.js';
 import { DeviceUtilities } from '../engine/engine_utils.js';
 import { Behaviour } from './Component.js';
 
-/** 
- * Provides configuration options for the built-in Needle Menu.
- * Needle Menu uses HTML in 2D mode, and automatically switches to a 3D menu in VR/AR mode.
+/**
+ * [NeedleMenu](https://engine.needle.tools/docs/api/NeedleMenu) provides configuration for the built-in UI menu.
+ * The menu renders as HTML overlay in browser mode and automatically
+ * switches to a 3D spatial menu in VR/AR.    
  * 
- * Controls display options, button visibility, and menu positioning.
- * From code, you can access the menu via {@link Context.menu}. 
- * 
- * @summary Configuration component for the Needle Menu
+ * ![](https://cloud.needle.tools/-/media/YKleg1oPy_I8Hv8sg_k40Q.png)
+ *
+ * **Features:**
+ * - Fullscreen toggle button
+ * - Audio mute/unmute button
+ * - QR code sharing (desktop only)
+ * - Spatial menu in XR (appears when looking up)
+ * - Custom positioning (top/bottom)  
+ *
+ * **Programmatic access:**
+ * Access the menu API via `this.context.menu` to add custom buttons,
+ * show/hide elements, or modify behavior at runtime.
+ *
+ * @example Configure menu from code
+ * ```ts
+ * // Access the menu API
+ * this.context.menu.appendChild(myCustomButton);
+ * this.context.menu.setPosition("top");
+ * this.context.menu.showFullscreenOption(true);
+ * ```
+ *
+ * @summary Configuration component for the Needle Menu overlay
  * @category User Interface
  * @group Components
+ * @see {@link Context.menu} for programmatic menu control
+ * @see {@link Voip} adds a microphone button to the menu
+ * @see {@link ScreenCapture} adds a screen sharing button
  **/
 export class NeedleMenu extends Behaviour {
 

package/src/engine-components/NestedGltf.ts

@@ -8,26 +8,62 @@ import { EventList } from "./EventList.js";
 
 const debug = getParam("debugnestedgltf");
 
-/** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
- * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+/**
+ * NestedGltf loads and instantiates a glTF file when the component starts.   
+ * NestedGltf components are created by the Unity exporter when nesting Objects with the GltfObject component (in Unity).  
+ * Use this for lazy-loading content, modular scene composition, or dynamic asset loading.  
  * 
+ * ![](https://cloud.needle.tools/-/media/lJKrr_2tWlqRFdFc46U4bQ.gif)
+ *
+ * The loaded glTF is instantiated as a sibling (child of parent) by default,  
+ * inheriting the transform of the GameObject with this component.  
+ *
+ * **Features:**  
+ * - Automatic loading on start
+ * - Progress callbacks for loading UI
+ * - Preloading support for faster display
+ * - Event callback when loading completes
+ *
+ * @example Load a glTF when object becomes active
+ * ```ts
+ * const nested = myPlaceholder.addComponent(NestedGltf);
+ * nested.filePath = new AssetReference("models/furniture.glb");
+ * nested.loaded.addEventListener(({ instance }) => {
+ *   console.log("Loaded:", instance.name);
+ * });
+ * ```
+ *
+ * @example Preload for instant display
+ * ```ts
+ * // Preload during loading screen
+ * await nested.preload();
+ * // Later, when object becomes active, it displays instantly
+ * ```
+ *
  * @summary Loads and instantiates a nested glTF file
  * @category Asset Management
  * @group Components
+ * @see {@link AssetReference} for asset loading utilities
+ * @see {@link SceneSwitcher} for scene-level loading
+ * @link https://engine.needle.tools/samples/hotspots
  */
 export class NestedGltf extends Behaviour {
 
-    /**  A reference to the gltf file that should be loaded */
+    /** Reference to the glTF file to load. Can be a URL or asset path. */
     @serializable(AssetReference)
     filePath?: AssetReference;
 
-    /** Invoked when the nested glTF file has been instantiated */
+    /**
+     * Event fired when the glTF has been loaded and instantiated.
+     * Provides the component, loaded instance, and asset reference.
+     */
     @serializable(EventList)
     loaded: EventList<{ component: NestedGltf, instance: any, asset: AssetReference }> = new EventList();
 
     /**
      * EXPERIMENTAL for cloud asset loading
      */
+    @serializable()
     loadAssetInParent = true;
 
 

package/src/engine-components/OffsetConstraint.ts

@@ -5,11 +5,35 @@ import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * OffsetConstraint component allows an object to maintain a specified positional and rotational offset 
- * relative to another object, with options for alignment and leveling.
- * @summary Maintains positional and rotational offset relative to another object
+ * The [OffsetConstraint](https://engine.needle.tools/docs/api/OffsetConstraint) maintains a fixed positional and rotational offset relative to a target object.
+ * Useful for attaching objects to moving targets while preserving a specific spatial relationship.  
+ *
+ * **Use cases:**  
+ * - Camera following a player with offset
+ * - UI elements attached to characters
+ * - Weapons attached to hands
+ * - Objects orbiting around a target
+ *
+ * **Options:**  
+ * - `affectPosition` - Apply position offset
+ * - `affectRotation` - Apply rotation offset
+ * - `alignLookDirection` - Make object face same direction as target
+ * - `levelLookDirection` - Keep look direction horizontal (ignore pitch)
+ * - `levelPosition` - Project position onto horizontal plane
+ * - `referenceSpace` - Transform offset in this object's coordinate space
+ *
+ * @example Attach camera offset to player
+ * ```ts
+ * const constraint = camera.addComponent(OffsetConstraint);
+ * // Configure via serialized properties in editor
+ * ```
+ *
+ * @summary Maintains positional/rotational offset relative to target
  * @category Constraints
  * @group Components
+ * @see {@link SmoothFollow} for smoothed following
+ * @see {@link LookAtConstraint} for aim constraints
+ * @see {@link AlignmentConstraint} for alignment between two objects
  */
 export class OffsetConstraint extends Behaviour {