@needle-tools/engine 4.13.0 → 4.13.1

package/plugins/vite/custom-element-data.js

@@ -1,12 +1,63 @@
 import fs from 'fs';
 import path from 'path';
 
+/** Known needle-engine tag names that should be updated from the source */
+const NEEDLE_TAG_NAMES = ['needle-engine', 'needle-menu', 'needle-button'];
+
 /**
- * Ensure the repo workspace or .vscode settings include Needle Engine custom HTML data if they exist
- * - Adds `./../node_modules/@needle-tools/engine/custom-elements.json`  
- *   to `.code-workspace settings.html.customData`
- * - Adds `./node_modules/@needle-tools/engine/custom-elements.json`  
- *   to `.vscode/settings.json html.customData`
+ * Merges needle-engine custom element data into an existing custom-elements.json file.
+ * Preserves user-defined tags while updating needle-engine specific tags.
+ * @param {object} sourceData - The needle-engine custom-elements.json data
+ * @param {object} targetData - The existing project custom-elements.json data
+ * @returns {object} Merged data
+ */
+function mergeCustomElementData(sourceData, targetData) {
+    const merged = { ...targetData };
+
+    // Ensure basic structure
+    merged.version = sourceData.version || targetData.version || 1.1;
+    merged.tags = merged.tags || [];
+    merged.globalAttributes = merged.globalAttributes || targetData.globalAttributes || [];
+    merged.valueSets = merged.valueSets || targetData.valueSets || [];
+
+    // Get source tags (needle-engine tags)
+    const sourceTags = sourceData.tags || [];
+
+    // Update or add needle-engine tags
+    for (const sourceTag of sourceTags) {
+        const existingIndex = merged.tags.findIndex(t => t.name === sourceTag.name);
+        if (existingIndex >= 0) {
+            // Replace existing needle-engine tag with updated version
+            if (NEEDLE_TAG_NAMES.includes(sourceTag.name)) {
+                merged.tags[existingIndex] = sourceTag;
+            }
+            // Otherwise keep existing (user-defined) tag
+        } else {
+            // Add new tag
+            merged.tags.push(sourceTag);
+        }
+    }
+
+    // Merge valueSets (avoid duplicates by name)
+    const sourceValueSets = sourceData.valueSets || [];
+    for (const sourceSet of sourceValueSets) {
+        const existingIndex = merged.valueSets.findIndex(s => s.name === sourceSet.name);
+        if (existingIndex >= 0) {
+            merged.valueSets[existingIndex] = sourceSet;
+        } else {
+            merged.valueSets.push(sourceSet);
+        }
+    }
+
+    return merged;
+}
+
+/**
+ * Ensure the repo workspace or .vscode settings include Needle Engine custom HTML data if they exist.
+ * Copies custom-elements.json to the project and merges with existing user content.
+ * - Copies/merges `custom-elements.json` to project root
+ * - Adds `./custom-elements.json` to `.code-workspace settings.html.customData`
+ * - Adds `./custom-elements.json` to `.vscode/settings.json html.customData`
  * @param {string} command
  * @param {import('../types').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
@@ -21,6 +72,52 @@ export const needleCustomElementData = (command, config, userSettings = {}) => {
             try {
                 const cwd = process.cwd();
 
+                // Path to source custom-elements.json in node_modules
+                const sourceFile = path.join(cwd, 'node_modules', '@needle-tools', 'engine', 'custom-elements.json');
+                // Path to target custom-elements.json in project root
+                const targetFile = path.join(cwd, 'custom-elements.json');
+
+                // Copy/merge custom-elements.json to project
+                if (fs.existsSync(sourceFile)) {
+                    try {
+                        const sourceData = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
+
+                        let targetData = {};
+                        if (fs.existsSync(targetFile)) {
+                            // Merge with existing file to preserve user content
+                            try {
+                                targetData = JSON.parse(fs.readFileSync(targetFile, 'utf8'));
+                            } catch {
+                                targetData = {};
+                            }
+                        }
+
+                        const mergedData = mergeCustomElementData(sourceData, targetData);
+                        const newContent = JSON.stringify(mergedData, null, 2);
+
+                        // Only write if content changed
+                        const existingContent = fs.existsSync(targetFile)
+                            ? fs.readFileSync(targetFile, 'utf8')
+                            : '';
+                        if (newContent !== existingContent) {
+                            fs.writeFileSync(targetFile, newContent, 'utf8');
+                        }
+                    } catch (err) {
+                        // Fallback: just copy the file if merge fails
+                        try {
+                            fs.copyFileSync(sourceFile, targetFile);
+                        } catch {
+                            // ignore
+                        }
+                    }
+                }
+
+                // Local path for VSCode settings (now points to project root)
+                const localCustomDataPath = './custom-elements.json';
+                // Old path in node_modules (to remove/replace)
+                const oldNodeModulesPath = './node_modules/@needle-tools/engine/custom-elements.json';
+                const oldWorkspaceNodeModulesPath = './../node_modules/@needle-tools/engine/custom-elements.json';
+
                 // 1) workspace file(s)
                 const files = fs.readdirSync(cwd);
                 const workspaceFiles = files.filter(f => f.endsWith('.code-workspace'));
@@ -30,12 +127,19 @@ export const needleCustomElementData = (command, config, userSettings = {}) => {
                         const raw = fs.readFileSync(full, 'utf8');
                         const data = JSON.parse(raw);
 
-                        // Ensure settings.html.customData contains the workspace-relative path
+                        // Ensure settings.html.customData contains the local path
                         data.settings = data.settings || {};
                         data.settings['html.customData'] = data.settings['html.customData'] || [];
-                        const wantedCustomData = './../node_modules/@needle-tools/engine/custom-elements.json';
-                        if (!data.settings['html.customData'].includes(wantedCustomData)) {
-                            data.settings['html.customData'].push(wantedCustomData);
+
+                        // Remove old node_modules path if present
+                        const oldIndex = data.settings['html.customData'].indexOf(oldWorkspaceNodeModulesPath);
+                        if (oldIndex >= 0) {
+                            data.settings['html.customData'].splice(oldIndex, 1);
+                        }
+
+                        // Add local path if not present
+                        if (!data.settings['html.customData'].includes(localCustomDataPath)) {
+                            data.settings['html.customData'].push(localCustomDataPath);
 
                             const newRaw = JSON.stringify(data, null, 2);
                             fs.writeFileSync(full, newRaw, 'utf8');
@@ -47,21 +151,26 @@ export const needleCustomElementData = (command, config, userSettings = {}) => {
 
                 // 2) .vscode/settings.json
                 const vscodeDir = path.join(cwd, '.vscode');
-
                 const settingsFile = path.join(vscodeDir, 'settings.json');
-                /** @type {Record<string, any>} */
-                let settings = {};
-                let rawSettings = "";
+
                 if (fs.existsSync(settingsFile)) {
                     try {
-                        rawSettings = fs.readFileSync(settingsFile, 'utf8');
-                        settings = JSON.parse(rawSettings) || {};
+                        const rawSettings = fs.readFileSync(settingsFile, 'utf8');
+                        /** @type {Record<string, any>} */
+                        const settings = JSON.parse(rawSettings) || {};
 
                         settings['html.customData'] = settings['html.customData'] || [];
-                        const wantedCustomData = './node_modules/@needle-tools/engine/custom-elements.json';
-                        if (!settings['html.customData'].includes(wantedCustomData)) {
-                            settings['html.customData'].push(wantedCustomData);
-                        
+
+                        // Remove old node_modules path if present
+                        const oldIndex = settings['html.customData'].indexOf(oldNodeModulesPath);
+                        if (oldIndex >= 0) {
+                            settings['html.customData'].splice(oldIndex, 1);
+                        }
+
+                        // Add local path if not present
+                        if (!settings['html.customData'].includes(localCustomDataPath)) {
+                            settings['html.customData'].push(localCustomDataPath);
+
                             // Write back settings.json if changed
                             const newRawSettings = JSON.stringify(settings, null, 2);
                             fs.writeFileSync(settingsFile, newRawSettings, 'utf8');

package/src/engine/engine_context.ts

@@ -97,15 +97,31 @@ export class ContextArgs {
 	scene?: Scene;
 }
 
+/**
+ * Represents the different phases of the update cycle in Needle Engine.  
+ * Components can register for specific frame events to perform actions at precise moments.  
+ * The order of execution is: Start → EarlyUpdate → Update → LateUpdate → OnBeforeRender → OnAfterRender  
+ *
+ * @see {@link Component.startCoroutine} for using FrameEvent with coroutines
+ */
 export enum FrameEvent {
+	/** Called once when a component starts for the first time */
 	Start = -1,
+	/** Called at the beginning of each frame, before the main update */
 	EarlyUpdate = 0,
+	/** The main update phase, called once per frame */
 	Update = 1,
+	/** Called after all Update callbacks have finished */
 	LateUpdate = 2,
+	/** Called immediately before the scene is rendered */
 	OnBeforeRender = 3,
+	/** Called after the scene has been rendered */
 	OnAfterRender = 4,
+	/** Called before each physics simulation step */
 	PrePhysicsStep = 9,
+	/** Called after each physics simulation step */
 	PostPhysicsStep = 10,
+	/** Default value when no specific frame event is set */
 	Undefined = -1,
 }
 

package/src/engine/engine_gameobject.ts

@@ -152,6 +152,29 @@ export function setDontDestroy(instance: Object3D | Component, value: boolean =
 
 const destroyed_components: Array<IComponent> = [];
 const destroyed_objects: Array<Object3D> = [];
+
+/**
+ * Destroys a GameObject or Component, removing it from the scene and cleaning up resources.  
+ * Calls `onDisable()` and `onDestroy()` lifecycle methods on all affected components.  
+ *
+ * @param instance The Object3D or Component to destroy
+ * @param recursive If true (default), also destroys all children recursively
+ * @param dispose If true, also disposes GPU resources (geometries, materials, textures)
+ *
+ * @example Destroy an object
+ * ```ts
+ * import { destroy } from "@needle-tools/engine";
+ * destroy(this.gameObject);
+ * ```
+ *
+ * @example Destroy with resource disposal
+ * ```ts
+ * destroy(myObject, true, true); // recursive + dispose GPU resources
+ * ```
+ *
+ * @see {@link GameObject.destroy} for the static method equivalent
+ * @see {@link setDontDestroy} to mark objects as non-destroyable
+ */
 export function destroy(instance: Object3D | Component, recursive: boolean = true, dispose: boolean = false) {
     destroyed_components.length = 0;
     destroyed_objects.length = 0;
@@ -224,6 +247,22 @@ function internalDestroy(instance: Object3D | Component, recursive: boolean = tr
 
 declare type ForEachComponentCallback = (comp: Component) => any;
 
+/**
+ * Iterates over all components on an Object3D and optionally its children.
+ * The callback can return a value to stop iteration early.
+ *
+ * @param instance The Object3D to iterate components on
+ * @param cb Callback function called for each component. Return a value to stop iteration.
+ * @param recursive If true (default), also iterates components on all children
+ * @returns The first non-undefined value returned by the callback, or undefined
+ *
+ * @example Find first Rigidbody in hierarchy
+ * ```ts
+ * const rb = foreachComponent(myObject, comp => {
+ *   if (comp instanceof Rigidbody) return comp;
+ * });
+ * ```
+ */
 export function foreachComponent(instance: Object3D, cb: ForEachComponentCallback, recursive: boolean = true): any {
     return internalForEachComponent(instance, cb, recursive);
 }
@@ -294,6 +333,40 @@ declare type NewObjectReferenceMap = Record<string, { target: object, key: strin
  */
 export declare type InstantiateContext = Readonly<InstantiateReferenceMap>;
 
+/**
+ * Creates a copy (clone) of a GameObject or loads and instantiates an AssetReference.
+ * All components on the original object are cloned and `awake()` is called on them.
+ *
+ * @param instance The Object3D to clone, or an AssetReference to load and instantiate
+ * @param opts Optional instantiation settings (position, rotation, scale, parent)
+ * @returns The cloned GameObject, or a Promise<Object3D> if instantiating from AssetReference
+ *
+ * @example Clone an object
+ * ```ts
+ * import { instantiate } from "@needle-tools/engine";
+ * const clone = instantiate(original);
+ * clone.position.set(1, 0, 0);
+ * this.context.scene.add(clone);
+ * ```
+ *
+ * @example Instantiate with options
+ * ```ts
+ * const clone = instantiate(original, {
+ *   parent: parentObject,
+ *   position: new Vector3(0, 1, 0),
+ *   rotation: new Quaternion()
+ * });
+ * ```
+ *
+ * @example Instantiate from AssetReference
+ * ```ts
+ * const instance = await instantiate(myAssetRef);
+ * if (instance) this.context.scene.add(instance);
+ * ```
+ *
+ * @see {@link GameObject.instantiate} for the static method equivalent
+ * @see {@link destroy} to remove instantiated objects
+ */
 export function instantiate(instance: AssetReference, opts?: IInstantiateOptions | null): Promise<Object3D | null>
 export function instantiate(instance: GameObject | Object3D, opts?: IInstantiateOptions | null): GameObject
 export function instantiate(instance: AssetReference | GameObject | Object3D, opts?: IInstantiateOptions | null | undefined): GameObject | Promise<Object3D | null> {

package/src/engine/engine_input.ts

@@ -9,10 +9,17 @@ import { DeviceUtilities, type EnumToPrimitiveUnion, getParam } from './engine_u
 const debug = getParam("debuginput");
 
 
+/**
+ * Types of pointer input devices supported by Needle Engine.
+ */
 export const enum PointerType {
+    /** Mouse or trackpad input */
     Mouse = "mouse",
+    /** Touch screen input */
     Touch = "touch",
+    /** XR controller input (e.g., VR controllers) */
     Controller = "controller",
+    /** XR hand tracking input */
     Hand = "hand"
 }
 export type PointerTypeNames = EnumToPrimitiveUnion<PointerType>;
@@ -28,12 +35,23 @@ const enum KeyboardEnumType {
     KeyPressed = "keypress"
 }
 
+/**
+ * Event types that can be listened to via {@link Input.addEventListener}.
+ * @see {@link NEPointerEvent} for pointer event data
+ * @see {@link NEKeyboardEvent} for keyboard event data
+ */
 export const enum InputEvents {
+    /** Fired when a pointer button is pressed */
     PointerDown = "pointerdown",
+    /** Fired when a pointer button is released */
     PointerUp = "pointerup",
+    /** Fired when a pointer moves */
     PointerMove = "pointermove",
+    /** Fired when a key is pressed down */
     KeyDown = "keydown",
+    /** Fired when a key is released */
     KeyUp = "keyup",
+    /** Fired when a key produces a character value */
     KeyPressed = "keypress"
 }
 
@@ -81,7 +99,22 @@ export interface IPointerHitEventReceiver {
 export declare type NEPointerEventIntersection = Intersection & { event?: NEPointerEvent };
 
 /**
- * The Needle Engine Pointer Event is a custom event that extends the PointerEvent. It holds additional information like the device index, the origin of the event, the mode of the event (e.g. screen or spatial), the ray in world space, the space of the device, and more.
+ * Extended PointerEvent with Needle Engine-specific data.
+ * Contains information about the input device, spatial data for XR, and world-space ray.
+ *
+ * @example Accessing event data in a component
+ * ```ts
+ * onPointerDown(args: PointerEventData) {
+ *   const evt = args.event;
+ *   console.log(`Pointer ${evt.pointerId} (${evt.pointerType})`);
+ *   if (evt.isSpatial) {
+ *     console.log("XR input, ray:", evt.ray);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Input} for the input management system
+ * @see {@link PointerType} for available pointer types
  */
 export class NEPointerEvent extends PointerEvent {
 
@@ -255,7 +288,50 @@ declare type EventListenerOptions = {
 type RegisteredEventListenerValue = Array<{ priority: number, listeners: Array<{ callback: InputEventListener, options: EventListenerOptions }> }>;
 
 /**
- * The input system is responsible for handling all input events like pointer events (mouse, touch, xr controllers) and keyboard events.
+ * Handles all input events including mouse, touch, keyboard, and XR controllers.  
+ * Access via `this.context.input` from any component.
+ *
+ * @example Checking mouse/pointer state
+ * ```ts
+ * update() {
+ *   if (this.context.input.mouseDown) {
+ *     console.log("Mouse button pressed");
+ *   }
+ *   if (this.context.input.mouseClick) {
+ *     console.log("Click detected");
+ *   }
+ *   const pos = this.context.input.mousePosition;
+ *   console.log(`Mouse at: ${pos.x}, ${pos.y}`);
+ * }
+ * ```
+ * @example Keyboard input
+ * ```ts
+ * update() {
+ *   if (this.context.input.isKeyDown("Space")) {
+ *     console.log("Space pressed this frame");
+ *   }
+ *   if (this.context.input.isKeyPressed("w")) {
+ *     console.log("W key is held down");
+ *   }
+ * }
+ * ```
+ * @example Event-based input
+ * ```ts
+ * onEnable() {
+ *   this.context.input.addEventListener("pointerdown", this.onPointerDown);
+ * }
+ * onDisable() {
+ *   this.context.input.removeEventListener("pointerdown", this.onPointerDown);
+ * }
+ * onPointerDown = (evt: NEPointerEvent) => {
+ *   console.log("Pointer down:", evt.pointerId);
+ * }
+ * ```
+ *
+ * @see {@link NEPointerEvent} for pointer event data
+ * @see {@link InputEvents} for available event types
+ * @see {@link PointerType} for pointer device types
+ * @link https://engine.needle.tools/docs/scripting.html
  */
 export class Input implements IInput {
 
@@ -269,14 +345,14 @@ export class Input implements IInput {
      * @param type The event type to listen for
      * @param callback The callback to call when the event is triggered
      * @param options The options for adding the event listener.
-     * @example Basic usage:
+     * @example Basic usage
      * ```ts
-     * input.addEventListener("pointerdown", (evt) => { 
+     * input.addEventListener("pointerdown", (evt) => {
      *   console.log("Pointer down", evt.pointerId, evt.pointerType);
      * });
      * ```
-     * @example Adding a listener that is called after all other listeners    
-     * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).  
+     * @example Adding a listener that is called after all other listeners
+     * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).
      * ```ts
      * input.addEventListener("pointerdown", (evt) => {
      *  console.log("Pointer down", evt.pointerId, evt.pointerType);
@@ -285,7 +361,7 @@ export class Input implements IInput {
      * @example Adding a listener that is only called once
      * ```ts
      * input.addEventListener("pointerdown", (evt) => {
-     * console.log("Pointer down", evt.pointerId, evt.pointerType);
+     *   console.log("Pointer down", evt.pointerId, evt.pointerType);
      * }, { once: true });
      * ```
      */

package/src/engine/engine_math.ts

@@ -4,9 +4,40 @@ import type { Vec3 } from "./engine_types.js";
 
 declare type Vector = Vector3 | Vector4 | Vector2 | Quaternion;
 
+/**
+ * Math utility class providing common mathematical operations.  
+ * Access via the exported `Mathf` constant. 
+ *
+ * @example
+ * ```ts
+ * import { Mathf } from "@needle-tools/engine";
+ *
+ * // Random number between 0 and 10
+ * const rand = Mathf.random(0, 10);
+ *
+ * // Clamp a value
+ * const clamped = Mathf.clamp(value, 0, 100);
+ *
+ * // Smooth interpolation
+ * const smoothed = Mathf.lerp(start, end, t);
+ * ```
+ */
 class MathHelper {
 
+    /**
+     * Returns a random number or element.
+     * @param arr Array to pick a random element from
+     * @returns Random element from array, or null if array is empty
+     * @example `Mathf.random([1, 2, 3])` - returns random element
+     */
     random<T>(arr: Array<T>): T | null;
+    /**
+     * Returns a random number between min and max (inclusive).
+     * @param min Minimum value (inclusive)
+     * @param max Maximum value (inclusive)
+     * @returns Random number in range, or 0-1 if no args provided
+     * @example `Mathf.random(0, 10)` - returns 0 to 10
+     */
     random(min?: number, max?: number): number;
     random<T>(arrayOrMin?: number | Array<T>, max?: number): number | T | null {
         if (Array.isArray(arrayOrMin)) {
@@ -21,12 +52,25 @@ class MathHelper {
         return Math.random();
     }
 
+    /**
+     * Fills a Vector3 with random values.
+     * @param target Vector3 to fill with random values
+     * @param min Minimum value for each component
+     * @param max Maximum value for each component
+     */
     randomVector3(target: Vector3, min: number = 0, max: number = 1) {
         target.x = this.random(min, max);
         target.y = this.random(min, max);
         target.z = this.random(min, max);
     }
 
+    /**
+     * Clamps a value between min and max.
+     * @param value Value to clamp
+     * @param min Minimum bound
+     * @param max Maximum bound
+     * @returns Clamped value
+     */
     clamp(value: number, min: number, max: number) {
 
         if (value < min) {
@@ -39,12 +83,21 @@ class MathHelper {
         return value;
     }
 
+    /**
+     * Clamps a value between 0 and 1.
+     * @param value Value to clamp
+     * @returns Value clamped to [0, 1]
+     */
     clamp01(value: number) {
         return this.clamp(value, 0, 1);
     }
 
     /**
-     * Linear interpolate
+     * Linearly interpolates between two values.
+     * @param value1 Start value (returned when t=0)
+     * @param value2 End value (returned when t=1)
+     * @param t Interpolation factor, clamped to [0, 1]
+     * @returns Interpolated value
      */
     lerp(value1: number, value2: number, t: number) {
         t = t < 0 ? 0 : t;
@@ -53,7 +106,12 @@ class MathHelper {
     }
 
     /**
-     * 
+     * Calculates the linear interpolation parameter that produces the given value.
+     * Inverse of lerp: if `lerp(a, b, t) = v`, then `inverseLerp(a, b, v) = t`
+     * @param value1 Start value
+     * @param value2 End value
+     * @param t The value to find the parameter for
+     * @returns The interpolation parameter (may be outside [0,1] if t is outside [value1, value2])
      */
     inverseLerp(value1: number, value2: number, t: number) {
         return (t - value1) / (value2 - value1);
@@ -71,6 +129,14 @@ class MathHelper {
         return min2 + (max2 - min2) * (value - min1) / (max1 - min1);
     }
 
+    /**
+     * Moves a value towards a target by a maximum step amount.
+     * Useful for smooth following or gradual value changes.
+     * @param value1 Current value
+     * @param value2 Target value
+     * @param amount Maximum step to move (positive moves toward target)
+     * @returns New value moved toward target, never overshooting
+     */
     moveTowards(value1: number, value2: number, amount: number) {
         value1 += amount;
         if (amount < 0 && value1 < value2) value1 = value2;
@@ -108,6 +174,14 @@ class MathHelper {
         return Math.pow(linear, 1 / 2.2);
     }
 
+    /**
+     * Checks if two vectors are approximately equal within epsilon tolerance.
+     * Works with Vector2, Vector3, Vector4, and Quaternion.
+     * @param v1 First vector
+     * @param v2 Second vector
+     * @param epsilon Tolerance for comparison (default: Number.EPSILON)
+     * @returns True if all components are within epsilon of each other
+     */
     approximately(v1: Vector, v2: Vector, epsilon = Number.EPSILON) {
         for (const key of vectorKeys) {
             const a = v1[key];
@@ -121,6 +195,11 @@ class MathHelper {
         return true;
     }
 
+    /**
+     * Easing function: slow start, fast middle, slow end (cubic).
+     * @param x Input value from 0 to 1
+     * @returns Eased value from 0 to 1
+     */
     easeInOutCubic(x: number) {
         return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
     }