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

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/engine_utils_format.ts

@@ -16,7 +16,8 @@ export type NeedleMimetype = "unknown" | "unsupported" |
     "model/vnd.usdc" |
     "model/fbx" |
     "model/vnd.autodesk.fbx" |
-    "model/obj"
+    "model/obj" |
+    "application/materialx+xml"
     | (string & {})
 
 
@@ -95,6 +96,8 @@ export async function tryDetermineMimetypeFromURL(url: string, opts: { useExtens
                 return "model/vnd.usdz+zip";
             case "OBJ":
                 return "model/obj";
+            case "MTLX":
+                return "application/materialx+xml";
         }
     }
 
@@ -222,6 +225,7 @@ export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, r
             case "model/fbx":
             case "model/vnd.autodesk.fbx":
             case "model/obj":
+            case "application/materialx+xml":
                 return content_type;
             // case "model/stl":
             //     return "stl";
@@ -271,7 +275,7 @@ export function tryDetermineMimetypeFromBinary(url: string, data: ArrayBuffer, r
 
     if (isDevEnvironment() || debug) {
         const text = new TextDecoder().decode(data.slice(0, Math.min(data.byteLength, 32)));
-        console.warn(`Could not determine file type.\n\nConsider registering a custom loader via the 'onCreateCustomModelLoader' callback: 'NeedleEngineModelLoader.onCreateCustomModelLoader(args => { })'\n\nContent-Type: \"${response.headers.get("content-type")}\n\"Text: \"${text}\"\nBinary:`, bytes);
+        console.warn(`Could not determine file type.\n\nConsider registering a custom loader via the 'onCreateCustomModelLoader' callback: 'NeedleEngineModelLoader.onCreateCustomModelLoader(args => { })'\n\nContent-Type: \"${response.headers.get("content-type")}\"\n\"Text: \"${text}\"\nBinary:`, bytes);
     }
     else {
         console.debug(`Could not determine file type from binary data`);

package/src/engine/extensions/NEEDLE_materialx.ts

@@ -0,0 +1,143 @@
+import { Loader, LoadingManager, Material, Object3D, TextureLoader } from "three";
+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
+
+export namespace MaterialX {
+
+
+    /**
+     * Utility function to load a MaterialX material from a URL. This can be used in your own code to load MaterialX materials outside of the glTF loading process. The URL should point to a MaterialX XML file.
+     */
+    export async function loadFromUrl(urlOrXML: string,
+        opts?: {
+            url?: string,
+            loadingManager?: LoadingManager,
+            materialNameOrIndex?: number | string
+        }
+    ): Promise<import("three").Material | null> {
+
+        if (!urlOrXML) throw new Error("URL or XML string is required to load a MaterialX material");
+
+        // Ensure the MaterialX module is loaded
+        const module = await MODULES.MaterialX.load();
+
+        // Check if the input is an XML string or a URL
+        // And fetch the XML content if it's a URL
+        const isXmlString = urlOrXML.trimStart().startsWith("<");
+        const xml = isXmlString ? urlOrXML : await fetch(urlOrXML).then(r => r.text()).catch(console.error);
+        if (!xml) {
+            console.warn("Failed to load MaterialX file from url", urlOrXML);
+            return null;
+        }
+
+        // For relative texture paths we might need to detect the base directory of the material file. 
+        // We can only do this if we have a URL (not an XML string) and if the URL is not a data URL. In that case we can use the URL to determine the base path for textures.
+        // This can be used by the loader callback to resolve texture paths relative to the material file.
+        let dir: string | undefined = undefined;
+        if (opts?.url || !isXmlString) {
+            const parts = (opts?.url || urlOrXML).split('/');
+            parts.pop();
+            dir = parts.join('/');
+        }
+
+        const textureLoader = new TextureLoader();
+        return module.Experimental_API.createMaterialXMaterial(xml, opts?.materialNameOrIndex ?? 0, {
+            getTexture: async url => {
+                if (!url.startsWith("http") && !url.startsWith("data:") && !url.startsWith("blob:") && !url.startsWith("file:")) {
+                    if (dir) {
+                        url = dir + "/" + url;
+                    }
+                }
+                return textureLoader.loadAsync(url).catch(e => {
+                    console.warn(`Failed to load texture for MaterialX material ${url}`, e);
+                });
+            }
+        }, {
+            cacheKey: urlOrXML,
+        })
+    }
+}
+
+
+// #region Loader
+
+export class MaterialXLoader extends Loader<Object3D | null> {
+
+    loadAsync(url: string, onProgress?: ((event: ProgressEvent<EventTarget>) => void) | undefined): Promise<Object3D> {
+        return new Promise((resolve, reject) => {
+            this.load(url, resolve, onProgress, reject);
+        });
+    }
+
+    load(url: string, onLoad: (data: Object3D) => void, onProgress?: ((event: ProgressEvent<EventTarget>) => void) | undefined, onError?: ((err: unknown) => void) | undefined): void {
+        onProgress?.({ type: "progress", loaded: 0, total: 0 } as ProgressEvent);
+
+        MaterialX.loadFromUrl(url, {
+        }).then(mat => {
+            if (mat) {
+                onLoad(this.onLoaded(mat));
+            }
+            else {
+                onError?.(new Error("Failed to load MaterialX material from url: " + url));
+            }
+        });
+    }
+
+    private onLoaded(mat: Material): Object3D {
+        const shaderball = ObjectUtils.createPrimitive("ShaderBall", { material: mat });
+        return shaderball;
+    }
+}
+
+
+
+// #region GLTF Extension
+
+export class NEEDLE_materialx implements GLTFLoaderPlugin {
+
+    get name(): string {
+        return "materialx-loading-helper";
+    }
+
+    constructor(
+        private readonly context: IContext,
+        private readonly loader: GLTFLoader,
+        private readonly url: string,
+        private readonly parser: GLTFParser,
+    ) {
+    }
+
+    private mtlxLoader?: import("@needle-tools/materialx").MaterialXLoader;
+
+    async beforeRoot() {
+        const mtlxExtension = this.parser.json.extensions?.["NEEDLE_materials_mtlx"];
+        if (mtlxExtension) {
+            const module = await MODULES.MaterialX.load();
+            try {
+                this.mtlxLoader = new module.MaterialXLoader(this.parser, {
+                    cacheKey: `${this.url}:materialx`,
+                    parameters: {
+                        precision: this.context.renderer?.capabilities.precision as any,
+                    }
+                }, {
+                    getFrame: () => this.context.time.frame,
+                    getTime: () => this.context.time.time,
+                })
+            }
+            catch (error) {
+                console.error(error);
+            }
+        }
+    }
+
+    loadMaterial(index) {
+        if (this.mtlxLoader) return this.mtlxLoader.loadMaterial(index);
+        return null;
+    }
+}

package/src/engine/extensions/extensions.ts

@@ -12,6 +12,7 @@ import { EXT_texture_exr } from "./EXT_texture_exr.js";
 import { NEEDLE_components } from "./NEEDLE_components.js";
 import { NEEDLE_gameobject_data } from "./NEEDLE_gameobject_data.js";
 import { NEEDLE_lighting_settings } from "./NEEDLE_lighting_settings.js";
+import { NEEDLE_materialx } from "./NEEDLE_materialx.js";
 import { NEEDLE_persistent_assets } from "./NEEDLE_persistent_assets.js";
 import { NEEDLE_progressive } from "./NEEDLE_progressive.js";
 import { NEEDLE_render_objects } from "./NEEDLE_render_objects.js";
@@ -136,6 +137,7 @@ export async function registerExtensions(loader: GLTFLoader, context: Context, u
     loader.register(p => new NEEDLE_render_objects(p, sourceId));
     loader.register(p => new NEEDLE_progressive(p));
     loader.register(p => new EXT_texture_exr(p));
+    loader.register(p => new NEEDLE_materialx(context, loader, url, p));
     if (isResourceTrackingEnabled()) loader.register(p => new InternalUsageTrackerPlugin(p))
 
     await KHR_ANIMATIONPOINTER_IMPORT.catch(_ => { })

package/src/engine/extensions/index.ts

@@ -2,5 +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"

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.
+ * 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/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
+ * 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
+ * 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 component that 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 {