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

package/src/engine-components/CharacterController.ts

@@ -15,17 +15,48 @@ 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.
+ * 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;
 

package/src/engine-components/Collider.ts

@@ -14,17 +14,43 @@ import { Behaviour } from "./Component.js";
 import { Rigidbody } from "./RigidBody.js";
 
 /**
- * Collider is the base class for all colliders. A collider is a physical shape that is used to detect collisions with other objects in the scene.  
- * Colliders are used in combination with a {@link Rigidbody} to create physical interactions between objects.  
- * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.  
+ * Collider is the base class for all physics collision shapes.   
+ * Colliders define the physical boundary of objects for collision detection.   
  * 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * **Usage with Rigidbody:**  
+ * - Add a collider to define collision shape  
+ * - Add a {@link Rigidbody} to the same or parent object for physics simulation  
+ * - Without Rigidbody, collider acts as static geometry  
+ *
+ * **Trigger mode:**  
+ * Set `isTrigger = true` for detection without physical collision.  
+ * Triggers fire `onTriggerEnter`, `onTriggerStay`, `onTriggerExit` events.  
+ *
+ * **Collision filtering:**  
+ * Use `membership` and `filter` arrays to control which objects collide.  
+ *
+ * @example Add a box collider to an object  
+ * ```ts
+ * const collider = myObject.addComponent(BoxCollider);
+ * collider.size = new Vector3(1, 2, 1);
+ * collider.center = new Vector3(0, 1, 0);
+ * ```
+ *
  * - Example: https://samples.needle.tools/physics-basic
  * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation 
- * 
- * @summary Physics collider
- * @category Physics  
+ *
+ * @summary Physics collider base class
+ * @category Physics
  * @group Components
+ * @see {@link BoxCollider} for box-shaped colliders
+ * @see {@link SphereCollider} for sphere-shaped colliders
+ * @see {@link CapsuleCollider} for capsule-shaped colliders
+ * @see {@link MeshCollider} for mesh-based colliders
+ * @see {@link Rigidbody} for physics simulation
+ * @link https://engine.needle.tools/samples/?room=needle272&overlay=samples&tag=physics
+ * @link https://engine.needle.tools/samples-uploads/basic-physics/?showcolliders
  */
 export abstract class Collider extends Behaviour implements ICollider {
 
@@ -116,15 +142,26 @@ export abstract class Collider extends Behaviour implements ICollider {
 }
 
 /**
- * SphereCollider represents a sphere-shaped collision volume.
- * Useful for objects that are roughly spherical in shape or need a simple collision boundary.
+ * SphereCollider represents a sphere-shaped collision volume.  
+ * Efficient and suitable for balls, projectiles, or approximate collision bounds.  
  * 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * @example Create a bouncing ball
+ * ```ts
+ * const sphere = ball.addComponent(SphereCollider);
+ * sphere.radius = 0.5;
+ * const rb = ball.addComponent(Rigidbody);
+ * rb.mass = 1;
+ * ```
+ *
  * - Example: https://samples.needle.tools/physics-basic
- * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation 
- * 
+ *
+ * @summary Sphere-shaped physics collider
  * @category Physics
  * @group Components
+ * @see {@link Collider} for base collider functionality
+ * @see {@link CapsuleCollider} for elongated sphere shapes
  */
 export class SphereCollider extends Collider implements ISphereCollider {
 
@@ -167,15 +204,31 @@ export class SphereCollider extends Collider implements ISphereCollider {
 }
 
 /**
- * BoxCollider represents a box-shaped collision volume.
- * Ideal for rectangular objects or objects that need a simple cuboid collision boundary.
+ * BoxCollider represents a box-shaped (cuboid) collision volume.  
+ * Most common collider type, efficient for walls, floors, crates, and rectangular objects.  
  * 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
+ *
+ * @example Create a floor collider
+ * ```ts
+ * const box = floor.addComponent(BoxCollider);
+ * box.size = new Vector3(10, 0.1, 10);
+ * box.center = new Vector3(0, -0.05, 0);
+ * ```
+ *
+ * @example Auto-fit to mesh geometry
+ * ```ts
+ * const collider = BoxCollider.add(myMesh, { rigidbody: true });
+ * // Collider size is automatically set from mesh bounds
+ * ```
+ *
  * - Example: https://samples.needle.tools/physics-basic
- * - Example: https://samples.needle.tools/physics-playground
- * - Example: https://samples.needle.tools/physics-&-animation 
- * 
+ *
+ * @summary Box-shaped physics collider
  * @category Physics
  * @group Components
+ * @see {@link Collider} for base collider functionality
+ * @see {@link SphereCollider} for sphere shapes
  */
 export class BoxCollider extends Collider implements IBoxCollider {
 
@@ -274,8 +327,10 @@ export class BoxCollider extends Collider implements IBoxCollider {
 }
 
 /**
- * MeshCollider creates a collision shape from a mesh geometry.
- * Allows for complex collision shapes that match the exact geometry of an object.
+ * MeshCollider creates a collision shape from a mesh geometry.  
+ * Allows for complex collision shapes that match the exact geometry of an object.  
+ * 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
  * 
  * - Example: https://samples.needle.tools/physics-basic
  * - Example: https://samples.needle.tools/physics-playground
@@ -362,8 +417,10 @@ export class MeshCollider extends Collider {
 }
 
 /**
- * CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).
- * Ideal for character controllers and objects that need a rounded collision shape.
+ * CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).  
+ * Ideal for character controllers and objects that need a rounded collision shape.  
+ * 
+ * ![](https://cloud.needle.tools/-/media/slYWnXyaxdlrCqu8GP_lFQ.gif)
  * 
  * - Example: https://samples.needle.tools/physics-basic
  * - Example: https://samples.needle.tools/physics-playground

package/src/engine-components/ContactShadows.ts

@@ -44,19 +44,38 @@ type FitParameters = {
 // - node can simply be scaled in Y to adjust max. ground height
 
 /**
- * ContactShadows is a component that allows to display contact shadows in the scene. It has options for darkness, opacity and blur of the shadows.  
- * 
- * - Example: https://samples.needle.tools/contact-shadows
- * 
- * ## Usage
- * You can use {@link ContactShadows.auto} to automatically create a ContactShadows instance for the scene or you can add the component to an object in the scene. Note that the scale of the object will be used to define the size of the shadow area.  
- * 
- * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
+ * ContactShadows renders proximity-based soft shadows on flat surfaces.  
+ * Ideal for products or objects that need visual grounding without real-time shadows.    
  * 
+ * ![](https://cloud.needle.tools/-/media/87bPTNXHcsbV-An-oSEvHQ.gif)
+ *
+ * **Setup options:**  
+ * 1. `ContactShadows.auto(context)` - Auto-create and fit to scene  
+ * 2. Add component manually to control position and scale  
+ * 3. HTML attribute: `<needle-engine contactshadows="0.7">`  
+ *
+ * **Properties:**  
+ * - `opacity` / `darkness` - Shadow intensity  
+ * - `blur` - Softness of shadow edges
+ * - Object scale defines shadow area size
+ *
+ * **Debug:** Use `?debugcontactshadows` URL parameter.  
+ *
+ *
+ * @example Auto-create contact shadows
+ * ```ts
+ * const shadows = ContactShadows.auto(this.context);
+ * shadows.opacity = 0.5;
+ * shadows.darkness = 0.8;
+ * ```
+ *
  * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
-*/
+ * @see {@link Light} for real-time shadow casting
+ * @see {@link Renderer} for material/rendering control
+ * @link https://engine.needle.tools/samples/contact-shadows for a demo of contact shadows
+ */
 export class ContactShadows extends Behaviour {
 
     private static readonly _instances: Map<Context, ContactShadows> = new Map();
@@ -74,6 +93,7 @@ export class ContactShadows extends Behaviour {
         let instance = this._instances.get(context);
         if (!instance || instance.destroyed) {
             const obj = new Object3D();
+            obj.name = "ContactShadows";
             instance = addComponent(obj, ContactShadows, {
                 autoFit: false,
                 occludeBelowGround: false
@@ -160,6 +180,7 @@ export class ContactShadows extends Behaviour {
     private occluderMesh?: Mesh;
     private blurPlane?: Mesh;
 
+    private planeMaterial?: MeshBasicMaterial;
     private depthMaterial?: MeshDepthMaterial;
     private horizontalBlurMaterial?: ShaderMaterial;
     private verticalBlurMaterial?: ShaderMaterial;
@@ -257,7 +278,7 @@ export class ContactShadows extends Behaviour {
             // mat.depthWrite = false;
         }
 
-        const planeMaterial = new MeshBasicMaterial({
+        const planeMaterial = this.planeMaterial = new MeshBasicMaterial({
             map: this.renderTarget.texture,
             opacity: this.opacity,
             color: 0x000000,
@@ -295,7 +316,12 @@ export class ContactShadows extends Behaviour {
         this.shadowCamera = new OrthographicCamera(-1 / 2, 1 / 2, 1 / 2, -1 / 2, near, far);
         this.shadowCamera.layers.enableAll();
         this.shadowCamera.rotation.x = Math.PI / 2; // get the camera to look up
+        // Disable automatic matrix world updates because Camera.updateMatrixWorld
+        // resets scale to 1 which would break the shadow camera transform
+        this.shadowCamera.matrixWorldAutoUpdate = false;
         this.shadowGroup.add(this.shadowCamera);
+        // Update the local matrix after setting position/rotation
+        this.shadowCamera.updateMatrix();
 
         // like MeshDepthMaterial, but goes from black to transparent
         this.depthMaterial = new MeshDepthMaterial();
@@ -370,11 +396,16 @@ export class ContactShadows extends Behaviour {
         if (!this.renderTarget || !this.renderTargetBlur ||
             !this.depthMaterial || !this.shadowCamera ||
             !this.blurPlane || !this.shadowGroup || !this.plane ||
-            !this.horizontalBlurMaterial || !this.verticalBlurMaterial) {
+            !this.horizontalBlurMaterial || !this.verticalBlurMaterial || !this.planeMaterial) {
             if (debug) console.error("ContactShadows: not initialized yet");
             return;
         }
 
+        // Update properties that might have been changed
+        this.depthMaterial.userData.darkness.value = this.darkness;
+        this.planeMaterial.opacity = this.opacity;
+
+
         const scene = this.context.scene;
         const renderer = this.context.renderer;
         const initialRenderTarget = renderer.getRenderTarget();
@@ -442,6 +473,15 @@ export class ContactShadows extends Behaviour {
             }
         }
 
+        // Manually update shadow camera's matrix world without calling Camera.updateMatrixWorld
+        // (which would reset scale to 1 for glTF conformance)
+        if (this.shadowCamera.parent) {
+            this.shadowCamera.matrixWorld.multiplyMatrices(this.shadowCamera.parent.matrixWorld, this.shadowCamera.matrix);
+        } else {
+            this.shadowCamera.matrixWorld.copy(this.shadowCamera.matrix);
+        }
+        this.shadowCamera.matrixWorldInverse.copy(this.shadowCamera.matrixWorld).invert();
+
         // render to the render target to get the depths
         renderer.setRenderTarget(this.renderTarget);
         renderer.clear();

package/src/engine-components/DeleteBox.ts

@@ -10,11 +10,37 @@ import { UsageMarker } from "./Interactable.js";
 
 const debug = getParam("debugdeletable");
 /**
- * A box-shaped area that can be used to delete objects that get into it. Useful for sandbox-style builders or physics simulations.
+ * DeleteBox creates an invisible deletion zone that destroys objects entering it.
+ * Works with objects that have a {@link Deletable} component attached.  
  * 
+ * ![](https://cloud.needle.tools/-/media/J-Gmdhl214kfdjkfYViG8g.gif)
+ *
+ * **Use cases:**
+ * - Trash bins in sandbox builders
+ * - Kill zones in physics simulations
+ * - Cleanup areas for multiplayer scenes
+ *
+ * **Setup:**
+ * 1. Add DeleteBox to a GameObject with a BoxCollider-like shape
+ * 2. Add {@link Deletable} component to objects that should be destroyable
+ * 3. Objects entering the box will be destroyed (synced across network)
+ *
+ * **Debug:** Use `?debugdeletable` URL parameter to visualize deletion areas.
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
+ *
+ * @example Create a deletion zone
+ * ```ts
+ * const trashBin = trashBinModel.addComponent(DeleteBox);
+ * // Objects with Deletable component will be destroyed when entering
+ * ```
+ *
  * @summary Box area that deletes objects entering it
  * @category Interactivity
  * @group Components
+ * @see {@link Deletable} - Add to objects that can be destroyed
+ * @see {@link Duplicatable} for spawning objects
+ * @see {@link DragControls} for moving objects
  */
 export class DeleteBox extends BoxHelperComponent {
     static _instances: DeleteBox[] = [];
@@ -29,9 +55,24 @@ export class DeleteBox extends BoxHelperComponent {
     }
 }
 
-/** Objects with this component can be destroyed by the {@link DeleteBox} component.
+/**
+ * Marks a GameObject as deletable by {@link DeleteBox} zones.
+ * Objects with this component will be destroyed (and synced across network)
+ * when they enter a DeleteBox area.
+ *
+ * **Note:** Objects currently being used (with {@link UsageMarker}) are protected from deletion.
+ *
+ * @example Make an object deletable
+ * ```ts
+ * const deletable = spawnedObject.addComponent(Deletable);
+ * // Object can now be destroyed by entering a DeleteBox
+ * ```
+ *
+ * @summary Marks object as destroyable by DeleteBox
  * @category Interactivity
  * @group Components
+ * @see {@link DeleteBox} for the deletion trigger
+ * @see {@link UsageMarker} for protecting objects in use
  */
 export class Deletable extends Behaviour {
 

package/src/engine-components/DeviceFlag.ts

@@ -11,12 +11,31 @@ export enum DeviceType {
 }
 
 /**
- * Enables or disables the GameObject based on the device type (mobile or desktop).  
- * You can use this to show or hide objects depending on whether the user is on a mobile device or a desktop.
- * 
+ * DeviceFlag shows or hides GameObjects based on device type.  
+ * Use for responsive 3D content - show different UI, models, or interactions  
+ * depending on mobile vs desktop.  
+ *
+ * **Device types:**   
+ * - `Desktop` - Traditional computers with mouse/keyboard
+ * - `Mobile` - Phones and tablets with touch input
+ * - Combine with bitwise OR for multiple: `Desktop | Mobile`
+ *
+ * @example Show only on desktop
+ * ```ts
+ * const flag = myObject.addComponent(DeviceFlag);
+ * flag.visibleOn = DeviceType.Desktop;
+ * ```
+ *
+ * @example Show on both mobile and desktop
+ * ```ts
+ * flag.visibleOn = DeviceType.Desktop | DeviceType.Mobile;
+ * ```
+ *
  * @summary Show or hide GameObject based on device type
  * @category Utilities
  * @group Components
+ * @see {@link DeviceType} for device options
+ * @see {@link XRFlag} for XR-based visibility
  */
 export class DeviceFlag extends Behaviour {
 

package/src/engine-components/DragControls.ts

@@ -43,12 +43,42 @@ export enum DragMode {
 }
 
 /**
- * DragControls allows you to drag objects around in the scene. It can be used to move objects in 2D (screen space) or 3D (world space).
- * Debug mode can be enabled with the URL parameter `?debugdrag`, which shows visual helpers and logs drag operations.
+ * [DragControls](https://engine.needle.tools/docs/api/DragControls) enables interactive dragging of objects in 2D (screen space) or 3D (world space).  
+ *
+ * ![](https://cloud.needle.tools/-/media/HyrtRDLjdmndr23_SR4mYw.gif)
  * 
+ * **Drag modes:**  
+ * - `XZPlane` - Drag on horizontal plane (good for floor objects)
+ * - `Attached` - Follow pointer directly (screen plane in 2D, controller in XR)
+ * - `HitNormal` - Drag along the surface normal where clicked
+ * - `DynamicViewAngle` - Auto-switch between XZ and screen based on view angle
+ * - `SnapToSurfaces` - Snap to scene geometry while dragging
+ *
+ * **Features:**  
+ * - Works across desktop, mobile, VR, and AR
+ * - Optional grid snapping (`snapGridResolution`)
+ * - Rotation preservation (`keepRotation`)
+ * - Automatic networking with {@link SyncedTransform}  
+ * 
+ *
+ * **Debug:** Use `?debugdrag` URL parameter for visual helpers.
+ *
+ * @example Basic draggable object
+ * ```ts
+ * const drag = myObject.addComponent(DragControls);
+ * drag.dragMode = DragMode.XZPlane;
+ * drag.snapGridResolution = 0.5; // Snap to 0.5 unit grid
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
+ *
  * @summary Enables dragging of objects in 2D or 3D space
  * @category Interactivity
  * @group Components
+ * @see {@link DragMode} for available drag behaviors
+ * @see {@link Duplicatable} for drag-to-duplicate functionality
+ * @see {@link SyncedTransform} for networked dragging
+ * @see {@link ObjectRaycaster} for pointer detection
  */
 export class DragControls extends Behaviour implements IPointerEventHandler {
 

package/src/engine-components/DropListener.ts

@@ -3,7 +3,6 @@ import { Box3, Object3D, Vector2, Vector3 } from "three";
 import { isDevEnvironment } from "../engine/debug/index.js";
 import { AnimationUtils } from "../engine/engine_animation.js";
 import { Context } from "../engine/engine_context.js";
-import { destroy } from "../engine/engine_gameobject.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { getLoader } from "../engine/engine_gltf.js";
 import { BlobStorage } from "../engine/engine_networking_blob.js";
@@ -18,6 +17,8 @@ import { Behaviour } from "./Component.js";
 import { EventList } from "./EventList.js";
 import { Renderer } from "./Renderer.js";
 
+import type { AssetReference } from "../engine/engine_addressables.js"
+
 /**
  * Debug mode can be enabled with the URL parameter `?debugdroplistener`, which
  * logs additional information during drag and drop events and visualizes hit points.
@@ -109,40 +110,52 @@ class DropListenerAddedEvent<T extends DropListenerOnDropArguments> extends Cust
  */
 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.  
- * Existing child objects will behave like placeholders and will be removed when new files are dropped.  
- * 
- * 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}.
- * 
- * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
- * 
- * 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
- * 
- * @example
- * ```typescript
- * import { DropListener, DropListenerEvents } from "@needle-tools/engine";
- * 
- * const dropListener = new DropListener();
- * 
- * gameObject.addComponent(dropListener);
- * dropListener.on(DropListenerEvents.FileDropped, (evt) => {
- *   console.log("File dropped", evt.detail);
- *   const file = evt.detail as File;
- * });
+/**
+ * DropListener enables drag-and-drop loading of 3D files directly into your scene.  
+ * Users can drop glTF/GLB files onto the canvas to dynamically add new objects at runtime.   
  * 
+ * [![](https://cloud.needle.tools/-/media/p5LNPTQ0u4mRXA6WiSmzIQ.gif)](https://engine.needle.tools/samples/droplistener)  
+ *
+ * **Supported formats:** glTF, GLB, FBX, OBJ, USDZ, VRM  
+ *
+ * **Key features:**  
+ * - Drop files directly onto canvas or onto a specific {@link dropArea}
+ * - Paste URLs from clipboard (Ctrl/Cmd+V)
+ * - Auto-fit objects to a specific size with {@link fitIntoVolume}
+ * - Network sync to share dropped objects with other users
+ * - Special handling for GitHub and Polyhaven URLs
+ *
+ * **Events:**  
+ * - `file-dropped` - Fired for each dropped file
+ * - `object-added` - Fired when object is loaded and added to scene
+ *
+ * **Debug:** Use `?debugdroplistener` URL parameter
+ *
+ * @example Listen for dropped objects
+ * ```ts
+ * const dropListener = myObject.addComponent(DropListener);
+ * dropListener.useNetworking = true;
+ * dropListener.fitIntoVolume = true;
+ *
  * dropListener.on(DropListenerEvents.ObjectAdded, (evt) => {
- *    console.log("Object added", evt.detail);
- *    const gltf = evt.detail as GLTF;
+ *   const { object, model } = evt.detail;
+ *   console.log("Added:", object.name);
  * });
  * ```
- * 
- * @summary Component to handle drag and drop of files into the scene
+ *
+ * @example Load from URL programmatically  
+ * ```ts
+ * const obj = await dropListener.loadFromURL("https://example.com/model.glb");
+ * ```  
+ * Hint: We recommend to use {@link AssetReference} for preloading and referencing assets in code if you simply want to load a model.
+ *
+ * @summary Drag-and-drop file loading for 3D assets
  * @category Asset Management
  * @group Components
+ * @see {@link SceneSwitcher} for loading entire scenes
+ * @see {@link AssetReference} for preloading assets
+ * @see {@link SyncedTransform} for networking support
+ * @link https://engine.needle.tools/samples/droplistener for a live demo
  */
 export class DropListener extends Behaviour {