@needle-tools/engine 4.13.0 → 4.13.1-beta

package/src/engine/engine_utils.ts

@@ -111,11 +111,27 @@ export function getUrlParams() {
 // bit strange that we have to pass T in here as well but otherwise the type parameter is stripped it seems
 type Param<T extends string> = string | boolean | number | T;
 
-/** Checks if a url parameter exists.
- * Returns true if it exists but has no value (e.g. ?help)
- * Returns false if it does not exist
- * Returns false if it's set to 0 e.g. ?debug=0
- * Returns the value if it exists e.g. ?message=hello
+/**
+ * Checks if a URL parameter exists and returns its value.  
+ * Useful for debugging, feature flags, and configuration.  
+ *
+ * @param paramName The URL parameter name to check
+ * @returns
+ * - `true` if the parameter exists without a value (e.g. `?debug`)
+ * - `false` if the parameter doesn't exist or is set to `0`
+ * - The numeric value if it's a number (e.g. `?level=5` returns `5`)
+ * - The string value otherwise (e.g. `?name=test` returns `"test"`)
+ *
+ * @example Check debug mode
+ * ```ts
+ * if (getParam("debug")) {
+ *   console.log("Debug mode enabled");
+ * }
+ * ```
+ * @example Get a numeric value
+ * ```ts
+ * const level = getParam("level"); // Returns number if ?level=5
+ * ```
  */
 export function getParam<T extends string>(paramName: T): Param<T> {
     if (showHelp && !requestedParams.includes(paramName))

package/src/engine/extensions/NEEDLE_materialx.ts

@@ -1,8 +1,9 @@
 import { Loader, LoadingManager, Material, Object3D, TextureLoader } from "three";
-import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader";
-import { ObjectUtils } from "../engine_create_objects";
-import { MODULES } from "../engine_modules";
-import { IContext } from "../engine_types";
+import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+import { ObjectUtils } from "../engine_create_objects.js";
+import { MODULES } from "../engine_modules.js";
+import { IContext } from "../engine_types.js";
 
 
 // #region Utils

package/src/engine/extensions/index.ts

@@ -2,6 +2,6 @@ export { compareAssociation } from "./extension_utils.js"
 export * from "./extensions.js"
 export * from "./NEEDLE_animator_controller_model.js"
 export { SceneLightSettings } from "./NEEDLE_lighting_settings.js"
+export { MaterialX } from "./NEEDLE_materialx.js"
 export * from "./NEEDLE_progressive.js"
-export { CustomShader } from "./NEEDLE_techniques_webgl.js"
-export { MaterialX } from "./NEEDLE_materialx.js"
+export { CustomShader } from "./NEEDLE_techniques_webgl.js"

package/src/engine-components/AlignmentConstraint.ts

@@ -5,12 +5,32 @@ import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * Aligns this GameObject between two other GameObjects, scaling it to fit the distance.  
- * You can use this to create dynamic beams or connectors between objects.
+ * The [AlignmentConstraint](https://engine.needle.tools/docs/api/AlignmentConstraint) positions and scales this GameObject to span between two target objects.
+ * The object is rotated to face `to` and scaled along Z to match the distance.  
  *
- * @summary Aligns and scales the object between two target GameObjects
+ * **Use cases:**  
+ * - Dynamic beams or laser effects between objects  
+ * - Stretchy connectors or ropes  
+ * - Visual links between UI elements
+ * - Debug lines between transforms
+ *
+ * **How it works:**  
+ * - Position: Centered between `from` and `to` (or at `from` if not centered)
+ * - Rotation: Looks at `to` from `from`
+ * - Scale: Z-axis scales to match distance, X/Y use `width`
+ *
+ * @example Create a beam between two objects
+ * ```ts
+ * const beam = beamMesh.addComponent(AlignmentConstraint);
+ * // Set targets via serialized properties in editor
+ * // or via code if properties are exposed
+ * ```
+ *
+ * @summary Aligns and scales object between two targets
  * @category Constraints
- * @group Components 
+ * @group Components
+ * @see {@link LookAtConstraint} for rotation-only constraints
+ * @see {@link SmoothFollow} for following with smoothing
  **/
 export class AlignmentConstraint extends Behaviour {
 

package/src/engine-components/Animation.ts

@@ -10,6 +10,12 @@ import { Behaviour } from "./Component.js";
 
 const debug = getParam("debuganimation");
 
+/**
+ * Options for controlling animation playback via {@link Animation.play}.  
+ * All options are optional - defaults are sensible for most use cases.
+ *
+ * @see {@link Animation} for the component that uses these options
+ */
 export declare type PlayOptions = {
     /**
      * The fade duration in seconds for the action to fade in and other actions to fade out (if exclusive is enabled)
@@ -59,11 +65,47 @@ declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 class Vec2 { x!: number; y!: number }
 
 /**
- * Animation component to play animations on a GameObject.
+ * Animation component to play animations on a GameObject.  
+ * For simpler animation needs compared to {@link Animator}, this component directly  
+ * plays AnimationClips without state machine logic.  
+ *
+ * **Key features:**
+ * - Play animations by index, name, or clip reference
+ * - Cross-fade between animations with `fadeDuration`
+ * - Loop or play once with optional clamping
+ * - Random start time and speed variation
+ * - Promise-based completion handling
+ * 
  * 
- * @summary Plays animations from AnimationClips 
+ * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)  
+ *
+ * @example Play animation by name
+ * ```ts
+ * const anim = this.gameObject.getComponent(Animation);
+ * await anim?.play("Walk", { loop: true, fadeDuration: 0.3 });
+ * ```
+ *
+ * @example Play with options
+ * ```ts
+ * anim?.play(0, {
+ *   loop: false,
+ *   clampWhenFinished: true,
+ *   speed: 2
+ * });
+ * ```
+ *
+ * @summary Plays animations from AnimationClips
  * @category Animation and Sequencing
  * @group Components
+ * @see {@link Animator} for state machine-based animation
+ * @see {@link PlayOptions} for all playback options  
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
+ * @link https://engine.needle.tools/samples/imunogard/
+ * 
+ * @link https://engine.needle.tools/docs/blender/animation.html
+ * 
+ * ![](https://cloud.needle.tools/-/media/vAYv-kU-eMpICqQZHJktCA.gif)
+ * 
  */
 export class Animation extends Behaviour implements IAnimationComponent {
 

package/src/engine-components/Animator.ts

@@ -12,7 +12,7 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debuganimator");
 
 /** 
- * Represents an event emitted by an animation mixer
+ * Represents an event emitted by an animation mixer  
  * @category Animation and Sequencing
  * @group Components
  */
@@ -28,7 +28,7 @@ export declare class MixerEvent {
 }
 
 /**
- * Configuration options for playing animations
+ * Configuration options for playing animations  
  * @category Animation and Sequencing
  */
 export declare class PlayOptions {
@@ -38,15 +38,48 @@ export declare class PlayOptions {
     clampWhenFinished?: boolean;
 }
 
-/** 
- * The Animator component plays and manages animations on a GameObject. 
- * It works with an {@link AnimatorController} to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
+/**
+ * Animator plays and manages state-machine based animations on a GameObject.  
+ * Uses an {@link AnimatorController} for state transitions, blending, and parameters.  
+ *
+ * **State machine animations:**  
+ * Define animation states and transitions in Unity's Animator window or in [Blender's Animator Controller editor](https://engine.needle.tools/docs/blender/animation.html)
+ * Control transitions via parameters (bool, int, float, trigger).  
  * 
+ * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)  
+ *
+ * **Creating at runtime:**  
+ * Use `AnimatorController.createFromClips()` to create controllers from code.  
+ *
+ * **Parameters:**  
+ * - `setTrigger(name)` - Trigger a one-shot transition
+ * - `setBool(name, value)` - Set boolean parameter
+ * - `setFloat(name, value)` - Set float parameter
+ * - `setInteger(name, value)` - Set integer parameter
+ *
+ * @example Trigger animation state
+ * ```ts
+ * const animator = myCharacter.getComponent(Animator);
+ * animator.setTrigger("Jump");
+ * animator.setFloat("Speed", 5);
+ * animator.setBool("IsRunning", true);
+ * ```
+ *
+ * @example Listen to animation events
+ * ```ts
+ * animator.onLoop(evt => console.log("Animation looped"));
+ * animator.onFinished(evt => console.log("Animation finished"));
+ * ```
+ *
  * @summary Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
-*/
+ * @see {@link AnimatorController} for state machine configuration
+ * @see {@link Animation} for simple clip playback
+ * @see {@link PlayableDirector} for timeline-based animation
+ * 
+ * @link https://engine.needle.tools/docs/blender/animation.html
+ */
 export class Animator extends Behaviour implements IAnimationComponent {
 
     /** 

package/src/engine-components/AudioListener.ts

@@ -5,7 +5,7 @@ import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * AudioListener represents a listener that can hear audio sources in the scene.
+ * The [AudioListener](https://engine.needle.tools/docs/api/AudioListener) represents a listener that can hear audio sources in the scene.
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
  * 

package/src/engine-components/AudioSource.ts

@@ -37,24 +37,46 @@ export enum AudioRolloffMode {
 }
 
 
-/** 
- * Plays audio clips in the scene, with support for spatial positioning.
- * 
- * The AudioSource component can play audio files or media streams with
- * options for spatial blending, volume control, looping, and more.
- * 
- * When a page loses visibility (tab becomes inactive), audio will automatically
- * pause unless {@link playInBackground} is set to true. On mobile devices, audio always
- * pauses regardless of this setting. When the page becomes visible again,
- * previously playing audio will resume.
- * 
- * AudioSource also responds to application mute state changes. When the application
- * is muted, the volume is set to 0. When unmuted, the volume
- * returns to its previous value.
- * 
+/**
+ * Plays audio clips in the scene with support for spatial (3D) positioning.  
+ *
+ * **Browser autoplay policies:**  
+ * Web browsers require user interaction before playing audio. Use  
+ * `AudioSource.userInteractionRegistered` to check if playback is allowed,  
+ * or `registerWaitForAllowAudio()` to queue playback until interaction occurs.  
+ *
+ * **Spatial audio:**  
+ * Set `spatialBlend` to 1 for full 3D positioning, or 0 for 2D (non-spatial).  
+ * Requires an {@link AudioListener} in the scene (typically on the camera).  
+ *
+ * **Visibility handling:**  
+ * Audio automatically pauses when the tab is hidden unless `playInBackground = true`.  
+ * On mobile, audio always pauses in background regardless of this setting.  
+ *
+ * @example Play audio on button click
+ * ```ts
+ * onClick() {
+ *   const audio = this.getComponent(AudioSource);
+ *   audio.play();
+ * }
+ * ```
+ *
+ * @example Wait for user interaction
+ * ```ts
+ * AudioSource.registerWaitForAllowAudio(() => {
+ *   this.getComponent(AudioSource)?.play();
+ * });
+ * ```
+ *
  * @summary Plays audio clips from files or media streams
  * @category Multimedia
  * @group Components
+ * @see {@link AudioListener} for the audio receiver component
+ * @see {@link AudioRolloffMode} for distance attenuation options
+ * @see {@link Voip} for voice communication
+ * @see {@link PlayableDirector} for timeline-based audio  
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=audio
+ * @link https://spatial-audio-zubckswmztj.needle.run/
  */
 export class AudioSource extends Behaviour {
 

package/src/engine-components/AxesHelper.ts

@@ -5,12 +5,31 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * Component that visualizes the axes of an object in the scene.
- * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
- * 
- * @summary Visualizes object axes in the scene
+ * The [AxesHelper](https://engine.needle.tools/docs/api/AxesHelper) visualizes the local coordinate axes of an object.
+ * Displays colored lines for X (red), Y (green), and Z (blue) axes.
+ *
+ * **Use cases:**
+ * - Debugging object orientation and rotation
+ * - Visualizing pivot points
+ * - Understanding coordinate systems
+ *
+ * **Properties:**
+ * - `length` - Length of axis lines in world units
+ * - `depthTest` - Whether axes are occluded by scene objects
+ * - `isGizmo` - Only show when `?gizmos` URL parameter is set
+ *
+ * @example Add axes visualization
+ * ```ts
+ * const axes = myObject.addComponent(AxesHelper);
+ * axes.length = 2;
+ * axes.depthTest = false; // Always visible on top
+ * ```
+ *
+ * @summary Visualizes object axes (X=red, Y=green, Z=blue)
  * @category Helpers
  * @group Components
+ * @see {@link GridHelper} for grid visualization
+ * @see {@link Gizmos} for debug drawing utilities
  */
 export class AxesHelper extends Behaviour {
     /**

package/src/engine-components/BasicIKConstraint.ts

@@ -4,12 +4,35 @@ import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.  
- * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
- * 
- * @summary Simple Inverse Kinematics Constraint
- * @category Animation
+ * The [BasicIKConstraint](https://engine.needle.tools/docs/api/BasicIKConstraint) provides simple two-bone inverse kinematics.
+ * Positions this GameObject as a "joint" between `from` and `to` targets,
+ * using a `hint` object to determine the bend direction.
+ *
+ * **Use cases:**
+ * - Simple arm/leg IK (elbow/knee positioning)
+ * - Mechanical linkages
+ * - Procedural animation joints
+ *
+ * **How it works:**
+ * - Calculates joint position based on `desiredDistance` (bone length)
+ * - Uses `hint` to determine which way the joint bends
+ * - Automatically handles stretching when targets are too far apart
+ *
+ * @example Setup basic limb IK
+ * ```ts
+ * // Attach to the elbow/knee joint object
+ * const ik = elbowJoint.addComponent(BasicIKConstraint);
+ * // Configure via serialized properties in editor:
+ * // - from: shoulder/hip
+ * // - to: wrist/ankle
+ * // - hint: control point for bend direction
+ * ```
+ *
+ * @summary Two-bone inverse kinematics constraint
+ * @category Animation and Sequencing
  * @group Components
+ * @see {@link LookAtConstraint} for aim constraints
+ * @see {@link AlignmentConstraint} for simpler alignment
  */
 export class BasicIKConstraint extends Behaviour {
 

package/src/engine-components/Camera.ts

@@ -32,13 +32,43 @@ const debug = getParam("debugcam");
 const debugscreenpointtoray = getParam("debugscreenpointtoray");
 
 /**
- * Camera component that handles rendering from a specific viewpoint in the scene.
- * Supports both perspective and orthographic cameras with various rendering options.
- * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
+ * [Camera](https://engine.needle.tools/docs/api/Camera) handles rendering from a specific viewpoint in the scene.  
+ * Supports both perspective and orthographic cameras with various rendering options.  
+ * Internally uses three.js {@link PerspectiveCamera} or {@link OrthographicCamera}.    
  * 
+ * ![](https://cloud.needle.tools/-/media/UU96_SJNXdVjaAvPNW3kZA.webp)
+ *
+ * **Background clearing:**  
+ * Control how the camera clears the background using `clearFlags`:  
+ * - `Skybox` - Use scene skybox/environment
+ * - `SolidColor` - Clear with `backgroundColor`
+ * - `None` - Don't clear (for layered rendering)
+ *
+ * **Render targets:**  
+ * Set `targetTexture` to a {@link RenderTexture} to render to a texture  
+ * instead of the screen (useful for mirrors, portals, minimaps).  
+ * 
+ * [![](https://cloud.needle.tools/-/media/W4tYZuJVVJFVp7NTaHPOnA.gif)](https://engine.needle.tools/samples/movie-set)
+ *
+ * @example Configure camera settings
+ * ```ts
+ * const cam = this.context.mainCameraComponent;
+ * cam.fieldOfView = 60;
+ * cam.nearClipPlane = 0.1;
+ * cam.farClipPlane = 1000;
+ * cam.clearFlags = ClearFlags.SolidColor;
+ * cam.backgroundColor = new RGBAColor(0.1, 0.1, 0.2, 1);
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/multiple-cameras
+ *
  * @summary Rendering scenes from a specific viewpoint
  * @category Camera and Controls
  * @group Components
+ * @see {@link OrbitControls} for camera interaction
+ * @see {@link RenderTexture} for off-screen rendering
+ * @see {@link ClearFlags} for background clearing options
+ * @link https://engine.needle.tools/samples/movie-set/
  */
 export class Camera extends Behaviour implements ICamera {
 

package/src/engine-components/CharacterController.ts

@@ -14,18 +14,49 @@ import { Rigidbody } from "./RigidBody.js";
 const debug = getParam("debugcharactercontroller");
 
 /**
- * CharacterController adds a capsule collider and rigidbody to the object, constrains rotation, and provides movement and grounded state.  
- * It is designed for typical character movement in 3D environments.
+ * The [CharacterController](https://engine.needle.tools/docs/api/CharacterController) adds a capsule collider and rigidbody to the object, constrains rotation, and provides movement and grounded state.
+ * It is designed for typical character movement in 3D environments.  
+ *
+ * The controller automatically:
+ * - Creates a {@link CapsuleCollider} if one doesn't exist
+ * - Creates a {@link Rigidbody} if one doesn't exist
+ * - Locks rotation on all axes to prevent tipping over
+ * - Tracks ground contact for jump detection
+ *
+ * @example Basic character movement
+ * ```ts
+ * export class MyCharacter extends Behaviour {
+ *   @serializable(CharacterController)
+ *   controller?: CharacterController;
+ *
+ *   update() {
+ *     const input = this.context.input;
+ *     const move = new Vector3();
+ *     if (input.isKeyPressed("KeyW")) move.z = 0.1;
+ *     if (input.isKeyPressed("KeyS")) move.z = -0.1;
+ *     this.controller?.move(move);
+ *   }
+ * }
+ * ```
+ *
  * @summary Character Movement Controller
- * @category Character  
+ * @category Character
  * @group Components
+ * @see {@link CharacterControllerInput} for ready-to-use input handling
+ * @see {@link Rigidbody} for physics configuration
+ * @see {@link CapsuleCollider} for collision shape
  */
 export class CharacterController extends Behaviour {
 
+    /** Center offset of the capsule collider in local space */
     @serializable(Vector3)
     center: Vector3 = new Vector3(0, 0, 0);
+
+    /** Radius of the capsule collider */
     @serializable()
     radius: number = .5;
+
+    /** Height of the capsule collider */
     @serializable()
     height: number = 2;
 
@@ -70,6 +101,11 @@ export class CharacterController extends Behaviour {
         rb.lockRotationZ = true;
     }
 
+    /**
+     * Moves the character by adding the given vector to its position.
+     * Movement is applied directly without physics simulation.
+     * @param vec The movement vector to apply
+     */
     move(vec: Vector3) {
         this.gameObject.position.add(vec);
     }
@@ -92,9 +128,15 @@ export class CharacterController extends Behaviour {
         }
     }
 
+    /** Returns true if the character is currently touching the ground */
     get isGrounded(): boolean { return this._activeGroundCollisions.size > 0; }
 
     private _contactVelocity: Vector3 = new Vector3();
+
+    /**
+     * Returns the combined velocity of all objects the character is standing on.
+     * Useful for moving platforms - add this to your movement for proper platform riding.
+     */
     get contactVelocity(): Vector3 {
         this._contactVelocity.set(0, 0, 0);
         for (const col of this._activeGroundCollisions) {
@@ -110,31 +152,56 @@ export class CharacterController extends Behaviour {
 }
 
 /**
- * CharacterControllerInput handles user input to control a CharacterController.  
- * It supports movement, looking around, jumping, and double jumping.  
- * You can customize movement speed, rotation speed, and jump forces.  
- * It also integrates with an Animator component for character animations.
+ * CharacterControllerInput handles user input to control a {@link CharacterController}.
+ * It supports movement, looking around, jumping, and double jumping.
+ *
+ * Default controls:
+ * - **W/S**: Move forward/backward
+ * - **A/D**: Rotate left/right
+ * - **Space**: Jump (supports double jump)
+ *
+ * The component automatically sets animator parameters:
+ * - `running` (bool): True when moving
+ * - `jumping` (bool): True when starting a jump
+ * - `doubleJump` (bool): True during double jump
+ * - `falling` (bool): True when falling from height
+ *
+ * @example Custom input handling
+ * ```ts
+ * const input = this.gameObject.getComponent(CharacterControllerInput);
+ * input?.move(new Vector2(0, 1)); // Move forward
+ * input?.jump(); // Trigger jump
+ * ```
+ *
  * @summary User Input for Character Controller
  * @category Character
  * @group Components
+ * @see {@link CharacterController} for the movement controller
+ * @see {@link Animator} for animation integration
  */
 export class CharacterControllerInput extends Behaviour {
 
+    /** The CharacterController to drive with input */
     @serializable(CharacterController)
     controller?: CharacterController;
 
+    /** Movement speed multiplier */
     @serializable()
     movementSpeed: number = 2;
 
+    /** Rotation speed multiplier */
     @serializable()
     rotationSpeed: number = 2;
 
+    /** Impulse force applied when jumping from ground */
     @serializable()
     jumpForce: number = 1;
 
+    /** Impulse force applied for the second jump (set to 0 to disable double jump) */
     @serializable()
     doubleJumpForce: number = 2;
 
+    /** Optional Animator for character animations */
     @serializable(Animator)
     animator?: Animator;