@needle-tools/engine 4.2.5 → 4.3.0-alpha.1

package/src/engine-components/DropListener.ts

@@ -19,63 +19,104 @@ import { Animation } from "./Animation.js";
 import { Behaviour } from "./Component.js";
 import { EventList } from "./EventList.js";
 
+/**
+ * Debug mode can be enabled with the URL parameter `?debugdroplistener`, which
+ * logs additional information during drag and drop events and visualizes hit points.
+ */
 const debug = getParam("debugdroplistener");
 
+/**
+ * Events dispatched by the DropListener component
+ * @enum {string}
+ */
 export enum DropListenerEvents {
     /**
-     * Dispatched when a file is dropped into the scene. The detail of the event is the file that was dropped.
+     * Dispatched when a file is dropped into the scene. The detail of the event is the {@link File} that was dropped.
+     * The event is called once for each dropped file.
      */
     FileDropped = "file-dropped",
     /**
-     * Dispatched when a new object is added to the scene. The detail of the event is the glTF that was added.
+     * Dispatched when a new object is added to the scene. The detail of the event contains {@link DropListenerOnDropArguments} for the content that was added.
      */
     ObjectAdded = "object-added",
 }
 
+/**
+ * Context information for a drop operation
+ */
 declare type DropContext = {
+    /** Position where the file was dropped in screen coordinates */
     screenposition: Vector2;
+    /** URL of the dropped content, if applicable */
     url?: string,
+    /** File object of the dropped content, if applicable */
     file?: File;
+    /** 3D position where the content should be placed */
     point?: Vec3;
+    /** Size dimensions for the content */
     size?: Vec3;
 }
 
 
-/**  Networking event arguments for the DropListener component */
+/**  
+ * Network event arguments passed between clients when using the DropListener with networking
+ */
 export declare type DropListenerNetworkEventArguments = {
+    /** Unique identifier of the sender */
     guid: string,
+    /** Name of the dropped object */
     name: string,
+    /** URL or array of URLs to the dropped content */
     url: string | string[],
     /** Worldspace point where the object was placed in the scene */
     point: Vec3;
     /** Bounding box size */
     size: Vec3;
+    /** MD5 hash of the content for verification */
     contentMD5: string;
 }
 
+/**
+ * Arguments provided to handlers when an object is dropped or added to the scene
+ */
 export declare type DropListenerOnDropArguments = {
+    /** The DropListener component that processed the drop event */
     sender: DropListener,
-    /** the root object added to the scene */
+    /** The root object added to the scene */
     object: Object3D,
-    /** The whole dropped model */
+    /** The complete model with all associated data */
     model: Model,
+    /** MD5 hash of the content for verification */
     contentMD5: string;
+    /** The original dropped URL or File object */
     dropped: URL | File | undefined;
 }
 
-/** Dispatched when an object is dropped/changed */
+/**
+ * CustomEvent dispatched when an object is added to the scene via the DropListener
+ */
 class DropListenerAddedEvent<T extends DropListenerOnDropArguments> extends CustomEvent<T> {
+    /**
+     * Creates a new added event with the provided details
+     * @param detail Information about the added object
+     */
     constructor(detail: T) {
         super(DropListenerEvents.ObjectAdded, { detail });
     }
 }
 
+/**
+ * Key name used for blob storage parameters
+ */
 const blobKeyName = "blob";
 
 /** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene  
  * It can be used to allow users to drag and drop glTF files into the scene to add new objects.  
  * 
- * ## Events
+ * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
+ * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
+ * 
+ * The following events are dispatched by the DropListener:
  * - **object-added** - dispatched when a new object is added to the scene
  * - **file-dropped** - dispatched when a file is dropped into the scene
  * 
@@ -103,42 +144,46 @@ const blobKeyName = "blob";
 export class DropListener extends Behaviour {
 
     /**
-     * When enabled the DropListener will automatically network dropped files to other clients.
+     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
+     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
      */
     @serializable()
     useNetworking: boolean = true;
 
     /**
-     * When assigned the Droplistener will only accept files that are dropped on this object.
+     * When assigned, the DropListener will only accept files that are dropped on this specific object.
+     * This allows creating designated drop zones in your scene.
      */
     @serializable(Object3D)
     dropArea?: Object3D;
 
     /**
-     * When enabled the object will be fitted into a volume. Use {@link fitVolumeSize} to specify the volume size.
+     * When enabled, dropped objects will be automatically scaled to fit within the volume defined by fitVolumeSize.
+     * Useful for ensuring dropped models appear at an appropriate scale.
      * @default false
      */
     @serializable()
     fitIntoVolume: boolean = false;
 
     /**
-     * The volume size will be used to fit the object into the volume. Use {@link fitIntoVolume} to enable this feature.
+     * Defines the dimensions of the volume that dropped objects will be scaled to fit within.
+     * Only used when fitIntoVolume is enabled.
      */
     @serializable(Vector3)
     fitVolumeSize = new Vector3(1, 1, 1);
 
-    /** When enabled the object will be placed at the drop position (under the cursor)
+    /** 
+     * When enabled, dropped objects will be positioned at the point where the cursor hit the scene.
+     * When disabled, objects will be placed at the origin of the DropListener.
      * @default true
      */
     @serializable()
     placeAtHitPosition: boolean = true;
 
-
     /**
-     * Invoked after a file has been **added** to the scene.   
-     * Arguments are {@link DropListenerOnDropArguments}
+     * Event list that gets invoked after a file has been successfully added to the scene.
+     * Receives {@link DropListenerOnDropArguments} containing the added object and related information.
      * @event object-added
-     * @param {DropListenerOnDropArguments} evt
      * @example
      * ```typescript
      * dropListener.onDropped.addEventListener((evt) => {
@@ -178,6 +223,10 @@ export class DropListener extends Behaviour {
         this.removePreviouslyAddedObjects(false);
     }
 
+    /**
+     * Handles network events received from other clients containing information about dropped objects
+     * @param evt Network event data containing object information, position, and content URL
+     */
     private onNetworkEvent = (evt: DropListenerNetworkEventArguments) => {
         if (!this.useNetworking) {
             if (debug) console.debug("[DropListener] Ignoring networked event because networking is disabled", evt);
@@ -199,6 +248,11 @@ export class DropListener extends Behaviour {
         }
     }
 
+    /**
+     * Handles clipboard paste events and processes them as potential URL drops
+     * Only URLs are processed by this handler, and only when editing is allowed
+     * @param evt The paste event
+     */
     private handlePaste = (evt: Event) => {
         if (this.context.connection.allowEditing === false) return;
         if (evt.defaultPrevented) return;
@@ -217,12 +271,22 @@ export class DropListener extends Behaviour {
             .catch(console.warn);
     }
 
+    /**
+     * Handles drag events over the renderer's canvas
+     * Prevents default behavior to enable drop events
+     * @param evt The drag event
+     */
     private onDrag = (evt: DragEvent) => {
         if (this.context.connection.allowEditing === false) return;
         // necessary to get drop event
         evt.preventDefault();
     }
 
+    /**
+     * Processes drop events to add files to the scene
+     * Handles both file drops and text/URL drops
+     * @param evt The drop event
+     */
     private onDrop = async (evt: DragEvent) => {
         if (this.context.connection.allowEditing === false) return;
 
@@ -266,6 +330,14 @@ export class DropListener extends Behaviour {
         }
     }
 
+    /**
+     * Processes a dropped or pasted URL and tries to load it as a 3D model
+     * Handles special cases like GitHub URLs and Polyhaven asset URLs
+     * @param url The URL to process
+     * @param ctx Context information about where the drop occurred
+     * @param isRemote Whether this URL was shared from a remote client
+     * @returns The added object or null if loading failed
+     */
     private async addFromUrl(url: string, ctx: DropContext, isRemote: boolean) {
         if (debug) console.log("dropped url", url);
 
@@ -315,6 +387,12 @@ export class DropListener extends Behaviour {
 
     private _abort: AbortController | null = null;
 
+    /**
+     * Processes dropped files, loads them as 3D models, and handles networking if enabled
+     * Creates an abort controller to cancel previous uploads if new files are dropped
+     * @param fileList Array of dropped files
+     * @param ctx Context information about where the drop occurred
+     */
     private async addDroppedFiles(fileList: Array<File>, ctx: DropContext) {
         if (debug) console.log("Add files", fileList)
         if (!Array.isArray(fileList)) return;
@@ -361,7 +439,10 @@ export class DropListener extends Behaviour {
     private readonly _addedObjects = new Array<Object3D>();
     private readonly _addedModels = new Array<Model>();
 
-    /** Removes all previously added objects from the scene and removes those object references  */
+    /**
+     * Removes all previously added objects from the scene
+     * @param doDestroy When true, destroys the objects; when false, just clears the references
+     */
     private removePreviouslyAddedObjects(doDestroy: boolean = true) {
         if (doDestroy) {
             for (const prev of this._addedObjects) {
@@ -375,7 +456,13 @@ export class DropListener extends Behaviour {
     }
 
     /**
-     * Adds the object to the scene and fits it into the volume if {@link fitIntoVolume} is enabled.
+     * Adds a loaded model to the scene with proper positioning and scaling.
+     * Handles placement based on component settings and raycasting.
+     * If {@link fitIntoVolume} is enabled, the object will be scaled to fit within the volume defined by {@link fitVolumeSize}.
+     * @param data The loaded model data and content hash
+     * @param ctx Context information about where the drop occurred
+     * @param isRemote Whether this object was shared from a remote client
+     * @returns The added object or null if adding failed
      */
     private addObject(data: { model: Model, contentMD5: string }, ctx: DropContext, isRemote: boolean): Object3D | null {
 
@@ -444,6 +531,13 @@ export class DropListener extends Behaviour {
         return obj;
     }
 
+    /**
+     * Sends a network event to other clients about a dropped object
+     * Only triggered when networking is enabled and the connection is established
+     * @param url The URL to the content that was dropped
+     * @param obj The object that was added to the scene
+     * @param contentmd5 The content hash for verification
+     */
     private async sendDropEvent(url: string, obj: Object3D, contentmd5: string) {
         if (!this.useNetworking) {
             if (debug) console.debug("[DropListener] Ignoring networked event because networking is disabled", url);
@@ -463,12 +557,20 @@ export class DropListener extends Behaviour {
             this.context.connection.send("droplistener", evt);
         }
     }
+
+    /**
+     * Deletes remote state for this DropListener's objects
+     * Called when new files are dropped to clean up previous state
+     */
     private deleteDropEvent() {
         this.context.connection.sendDeleteRemoteState(this.guid);
     }
 
-
-
+    /**
+     * Tests if a drop event occurred within the designated drop area if one is specified
+     * @param ctx The drop context containing screen position information
+     * @returns True if the drop is valid (either no drop area is set or the drop occurred inside it)
+     */
     private testIfIsInDropArea(ctx: DropContext): boolean {
         if (this.dropArea) {
             const screenPoint = this.context.input.convertScreenspaceToRaycastSpace(ctx.screenposition.clone());
@@ -492,7 +594,11 @@ export class DropListener extends Behaviour {
 
 }
 
-
+/**
+ * Attempts to convert a Polyhaven website URL to a direct glTF model download URL
+ * @param urlStr The original Polyhaven URL
+ * @returns The direct download URL for the glTF model if it's a valid Polyhaven asset URL, otherwise returns the original URL
+ */
 function tryResolvePolyhavenAssetUrl(urlStr: string) {
     if (!urlStr.startsWith("https://polyhaven.com/")) return urlStr;
     // Handle dropping polyhaven image url
@@ -506,10 +612,18 @@ function tryResolvePolyhavenAssetUrl(urlStr: string) {
     return assetUrl;
 }
 
-
-
+/**
+ * Helper namespace for loading files and models from various sources
+ */
 namespace FileHelper {
 
+    /**
+     * Loads and processes a File object into a 3D model
+     * @param file The file to load (supported formats: gltf, glb, fbx, obj, usdz, vrm)
+     * @param context The application context
+     * @param args Additional arguments including a unique guid for instantiation
+     * @returns Promise containing the loaded model and its content hash, or null if loading failed
+     */
     export async function loadFile(file: File, context: Context, args: { guid: string }): Promise<{ model: Model, contentMD5: string } | null> {
         const name = file.name.toLowerCase();
         if (name.endsWith(".gltf") ||
@@ -544,6 +658,12 @@ namespace FileHelper {
         return null;
     }
 
+    /**
+     * Loads a 3D model from a URL with progress visualization
+     * @param url The URL to load the model from
+     * @param args Arguments including context, parent object, and optional placement information
+     * @returns Promise containing the loaded model and its content hash, or null if loading failed
+     */
     export async function loadFileFromURL(url: URL, args: { guid: string, context: Context, parent: Object3D, point?: Vec3, size?: Vec3 }): Promise<{ model: Model, contentMD5: string } | null> {
         return new Promise(async (resolve, _reject) => {
 

package/src/engine-components/Light.ts

@@ -24,82 +24,86 @@ const shadowMaxDistance = 300;
 const debug = getParam("debuglights");
 
 
-/// <summary>
-///   <para>The type of a Light.</para>
-/// </summary>
+/**
+ * Defines the type of light in a scene.
+ */
 export enum LightType {
-    /// <summary>
-    ///   <para>The light is a spot light.</para>
-    /// </summary>
+    /** Spot light that emits light in a cone shape */
     Spot = 0,
-    /// <summary>
-    ///   <para>The light is a directional light.</para>
-    /// </summary>
+    /** Directional light that emits parallel light rays in a specific direction */
     Directional = 1,
-    /// <summary>
-    ///   <para>The light is a point light.</para>
-    /// </summary>
+    /** Point light that emits light in all directions from a single point */
     Point = 2,
+    /** Area light */
     Area = 3,
-    /// <summary>
-    ///   <para>The light is a rectangle shaped area light. It affects only baked lightmaps and lightprobes.</para>
-    /// </summary>
+    /** Rectangle shaped area light that only affects baked lightmaps and light probes */
     Rectangle = 3,
-    /// <summary>
-    ///   <para>The light is a disc shaped area light. It affects only baked lightmaps and lightprobes.</para>
-    /// </summary>
+    /** Disc shaped area light that only affects baked lightmaps and light probes */
     Disc = 4,
 }
+
+/**
+ * Defines how a light contributes to the scene lighting.
+ */
 export enum LightmapBakeType {
-    /// <summary>
-    ///   <para>Realtime lights cast run time light and shadows. They can change position, orientation, color, brightness, and many other properties at run time. No lighting gets baked into lightmaps or light probes..</para>
-    /// </summary>
+    /** Light affects the scene in real-time with no baking */
     Realtime = 4,
-    /// <summary>
-    ///   <para>Baked lights cannot move or change in any way during run time. All lighting for static objects gets baked into lightmaps. Lighting and shadows for dynamic objects gets baked into Light Probes.</para>
-    /// </summary>
+    /** Light is completely baked into lightmaps and light probes */
     Baked = 2,
-    /// <summary>
-    ///   <para>Mixed lights allow a mix of realtime and baked lighting, based on the Mixed Lighting Mode used. These lights cannot move, but can change color and intensity at run time. Changes to color and intensity only affect direct lighting as indirect lighting gets baked. If using Subtractive mode, changes to color or intensity are not calculated at run time on static objects.</para>
-    /// </summary>
+    /** Combines aspects of realtime and baked lighting */
     Mixed = 1,
 }
 
-/// <summary>
-///   <para>Shadow casting options for a Light.</para>
-/// </summary>
+/**
+ * Defines the shadow casting options for a Light.
+ * @enum {number}
+ */
 enum LightShadows {
-    /// <summary>
-    ///   <para>Do not cast shadows (default).</para>
-    /// </summary>
+    /** No shadows are cast */
     None = 0,
-    /// <summary>
-    ///   <para>Cast "hard" shadows (with no shadow filtering).</para>
-    /// </summary>
+    /** Hard-edged shadows without filtering */
     Hard = 1,
-    /// <summary>
-    ///   <para>Cast "soft" shadows (with 4x PCF filtering).</para>
-    /// </summary>
+    /** Soft shadows with PCF filtering */
     Soft = 2,
 }
 
-/** The Light component can be used to create a light source in the scene.  
- * It can be used to create a directional light, a spot light or a point light.  
- * The light can be set to cast shadows and the shadow type can be set to hard or soft shadows.  
- * The light can be set to be baked or realtime.  
- * The light can be set to be a main light which will be used for the main directional light in the scene.
+/** 
+ * 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.
+ * 
  * @category Rendering
  * @group Components
  */
 export class Light extends Behaviour implements ILight {
 
+    /**
+     * The type of light (spot, directional, point, etc.)
+     */
     @serializable()
     private type: LightType = 0;
 
+    /**
+     * The maximum distance the light affects
+     */
     public range: number = 1;
+    
+    /**
+     * The full outer angle of the spotlight cone in degrees
+     */
     public spotAngle: number = 1;
+    
+    /**
+     * The angle of the inner cone in degrees for soft-edge spotlights
+     */
     public innerSpotAngle: number = 1;
 
+    /**
+     * The color of the light
+     */
     @serializable(Color)
     set color(val: Color) {
         this._color = val;
@@ -113,6 +117,9 @@ export class Light extends Behaviour implements ILight {
     }
     public _color: Color = new Color(0xffffff);
 
+    /**
+     * The near plane distance for shadow projection
+     */
     @serializable()
     set shadowNearPlane(val: number) {
         if (val === this._shadowNearPlane) return;
@@ -125,6 +132,9 @@ export class Light extends Behaviour implements ILight {
     get shadowNearPlane(): number { return this._shadowNearPlane; }
     private _shadowNearPlane: number = .1;
 
+    /**
+     * Shadow bias value to reduce shadow acne and peter-panning
+     */
     @serializable()
     set shadowBias(val: number) {
         if (val === this._shadowBias) return;
@@ -137,6 +147,9 @@ export class Light extends Behaviour implements ILight {
     get shadowBias(): number { return this._shadowBias; }
     private _shadowBias: number = 0;
 
+    /**
+     * Shadow normal bias to reduce shadow acne on sloped surfaces
+     */
     @serializable()
     set shadowNormalBias(val: number) {
         if (val === this._shadowNormalBias) return;
@@ -152,6 +165,9 @@ export class Light extends Behaviour implements ILight {
     /** when enabled this will remove the multiplication when setting the shadow bias settings initially */
     private _overrideShadowBiasSettings: boolean = false;
 
+    /**
+     * Shadow casting mode (None, Hard, or Soft)
+     */
     @serializable()
     set shadows(val: LightShadows) {
         this._shadows = val;
@@ -163,9 +179,16 @@ export class Light extends Behaviour implements ILight {
     get shadows(): LightShadows { return this._shadows; }
     private _shadows: LightShadows = 1;
 
+    /**
+     * Determines if the light contributes to realtime lighting, baked lighting, or a mix
+     */
     @serializable()
     private lightmapBakeType: LightmapBakeType = LightmapBakeType.Realtime;
 
+    /**
+     * Brightness of the light. In WebXR experiences, the intensity is automatically
+     * adjusted based on the AR session scale to maintain consistent lighting.
+     */
     @serializable()
     set intensity(val: number) {
         this._intensity = val;
@@ -184,6 +207,9 @@ export class Light extends Behaviour implements ILight {
     get intensity(): number { return this._intensity; }
     private _intensity: number = -1;
 
+    /**
+     * Maximum distance the shadow is projected
+     */
     @serializable()
     get shadowDistance(): number {
         const light = this.light;
@@ -207,6 +233,9 @@ export class Light extends Behaviour implements ILight {
     private shadowWidth?: number;
     private shadowHeight?: number;
 
+    /**
+     * Resolution of the shadow map in pixels (width and height)
+     */
     @serializable()
     get shadowResolution(): number {
         const light = this.light;
@@ -226,10 +255,16 @@ export class Light extends Behaviour implements ILight {
     }
     private _shadowResolution?: number = undefined;
 
+    /**
+     * Whether this light's illumination is entirely baked into lightmaps
+     */
     get isBaked() {
         return this.lightmapBakeType === LightmapBakeType.Baked;
     }
 
+    /**
+     * Checks if the GameObject itself is a {@link ThreeLight} object
+     */
     private get selfIsLight(): boolean {
         if (this.gameObject["isLight"] === true) return true;
         switch (this.gameObject.type) {
@@ -241,8 +276,16 @@ export class Light extends Behaviour implements ILight {
         return false;
     }
 
+    /**
+     * The underlying three.js {@link ThreeLight} instance
+     */
     private light: ThreeLight | undefined = undefined;
 
+    /**
+     * Gets the world position of the light
+     * @param vec Vector3 to store the result
+     * @returns The world position as a Vector3
+     */
     public getWorldPosition(vec: Vector3): Vector3 {
         if (this.light) {
             if (this.type === LightType.Directional) {
@@ -311,6 +354,10 @@ export class Light extends Behaviour implements ILight {
         // this.updateIntensity();
     }
 
+    /**
+     * Creates the appropriate three.js light based on the configured light type
+     * and applies all settings like shadows, intensity, and color.
+     */
     createLight() {
         const lightAlreadyCreated = this.selfIsLight;
 
@@ -447,6 +494,10 @@ export class Light extends Behaviour implements ILight {
 
     }
 
+    /**
+     * Coroutine that updates the main light reference in the context
+     * if this directional light should be the main light
+     */
     *updateMainLightRoutine() {
         while (true) {
             if (this.type === LightType.Directional) {
@@ -459,8 +510,14 @@ export class Light extends Behaviour implements ILight {
         }
     }
 
+    /**
+     * Controls whether the renderer's shadow map type can be changed when soft shadows are used
+     */
     static allowChangingRendererShadowMapType: boolean = true;
 
+    /**
+     * Updates shadow settings based on whether the shadows are set to hard or soft
+     */
     private updateShadowSoftHard() {
         if (!this.light) return;
         if (!this.light.shadow) return;
@@ -486,6 +543,10 @@ export class Light extends Behaviour implements ILight {
         }
     }
 
+    /**
+     * Configures a directional light by adding and positioning its target
+     * @param dirLight The directional light to set up
+     */
     private setDirectionalLight(dirLight: DirectionalLight) {
         dirLight.add(dirLight.target);
         dirLight.target.position.set(0, 0, -1);