@needle-tools/engine 4.13.0 → 4.13.1-beta

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](https://engine.needle.tools/docs/api/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();
@@ -161,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;
@@ -258,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,
@@ -376,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();

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.
+ * The [DeleteBox](https://engine.needle.tools/docs/api/DeleteBox) component 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

@@ -1,9 +1,9 @@
 import { Box3, Object3D, Vector2, Vector3 } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
+import type { AssetReference } from "../engine/engine_addressables.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";
@@ -109,40 +109,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 {
 

package/src/engine-components/Duplicatable.ts

@@ -12,26 +12,57 @@ import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.
 import { ObjectRaycaster } from "./ui/Raycaster.js";
 
 /**
- * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.   
- *  
+ * The [Duplicatable](https://engine.needle.tools/docs/api/Duplicatable) component creates clones of a GameObject when clicked/tapped/dragged.
+ * Perfect for spawning objects, creating drag-and-drop inventories, or multiplayer object creation.   
+ * 
+ * ![](https://cloud.needle.tools/-/media/J_ij9vxhh1zhS8h2ftGBXQ.gif)
+ *
+ * **How it works:**
+ * - When the user clicks on this object, it creates a clone of the assigned `object`  
+ * - The clone is automatically set up with {@link DragControls} so users can drag it   
+ * - If networking is enabled, clones are synced via {@link SyncedTransform}  
+ * - Rate limiting prevents spam (controlled by `limitCount`)  
+ *
+ * **Setup tips:**  
+ * - Assign `object` to a template object (it will be hidden and used as source)  
+ * - If `object` is not assigned, the component's own GameObject is used as template  
+ * - Add an {@link ObjectRaycaster} to enable pointer detection (added automatically if missing)  
+ *
+ * @example Basic duplicatable button
+ * ```ts
+ * const duplicatable = spawnButton.addComponent(Duplicatable);
+ * duplicatable.object = templateObject; // Object to clone
+ * duplicatable.parent = spawnContainer;  // Where to place clones
+ * duplicatable.limitCount = 10;          // Max 10 per second
+ * ```
+ *
  * @summary Duplicates a GameObject on pointer events
  * @category Interactivity
  * @group Components
+ * @see {@link DragControls} for dragging the duplicated objects
+ * @see {@link SyncedTransform} for networking support
+ * @see {@link GameObject.instantiateSynced} for the underlying instantiation
+ * @link https://engine.needle.tools/samples/collaborative-sandbox/
  */
 export class Duplicatable extends Behaviour implements IPointerEventHandler {
 
-    /** Duplicates will be parented into the set object. If not defined, this GameObject will be used as parent. */
+    /**
+     * Parent object for spawned duplicates.
+     * If not set, duplicates are parented to this GameObject's parent.
+     */
     @serializable(Object3D)
     parent: GameObject | null = null;
 
-    /** The object to be duplicated. If no object is assigned then the object the Duplicatable component is attached to will be used for cloning.
-     * @default null
+    /**
+     * Template object to duplicate. This object will be hidden and used as the source for clones.
+     * If not assigned, this GameObject itself is used as the template.
      */
     @serializable(Object3D)
     object: GameObject | null = null;
 
     /**
-     * The maximum number of objects that can be duplicated in the interval.
+     * Maximum duplications allowed per second to prevent spam.
+     * The counter decreases by 1 each second.
      * @default 60
      */
     @serializable()

package/src/engine-components/EventList.ts

@@ -4,6 +4,9 @@ import type { IComponent, IEventList } from "../engine/engine_types.js";
 
 const argumentsBuffer = new Array<any>();
 
+/**
+ * CallInfo represents a single callback method that can be invoked by the {@link EventList}.  
+ */
 export class CallInfo {
     /**
      * When the CallInfo is enabled it will be invoked when the EventList is invoked
@@ -101,24 +104,49 @@ export class EventListEvent<TArgs extends any> extends Event { //implements Arra
 
 
 /**
- * The EventList is a class that can be used to create a list of event listeners that can be invoked.  
- * 
- * @example
- * ```ts
- * // create an event list
- * const onClick = new EventList<(event: MouseEvent) => void>();
+ * EventList manages a list of callbacks that can be invoked together.  
+ * Used for Unity-style events that can be configured in the editor (Unity or Blender).  
+ *
+ * **Serialization:**  
+ * EventLists are serializable - callbacks configured in Unity/Blender will work at runtime.  
+ * Mark fields with `@serializable(EventList)` for editor support.  
+ *
+ * **Usage patterns:**  
+ * - Button click handlers
+ * - Animation events
+ * - Custom component callbacks
+ * - Scene loading events  
  * 
- * // add an event listener
- * onClick.addEventListener((event) => {
- *   console.log("Clicked!", event);
- * });
+ * ![](https://cloud.needle.tools/-/media/P7bEKQvfgRUMTb2Wi1hWXg.png)  
+ * *Screenshot of a Unity component with an EventList field*  
  * 
- * // invoke the event list
- * onClick.invoke(new MouseEvent("click"));
+ * ![](https://cloud.needle.tools/-/media/i2hi2OHfbaDyHyBL6Gt58A.png)  
+ * *Screenshot of a Blender component with an EventList field*
+ *
+ * @example Create and use an EventList
+ * ```ts
+ * // Define in your component
+ * @serializable(EventList)
+ * onClick: EventList = new EventList();
+ *
+ * // Add listeners
+ * this.onClick.addEventListener(() => console.log("Clicked!"));
+ *
+ * // Invoke all listeners
+ * this.onClick.invoke();
  * ```
- * 
+ *
+ * @example Listen with arguments
+ * ```ts
+ * const onScore = new EventList<{ points: number }>();
+ * onScore.addEventListener(data => console.log("Scored:", data.points));
+ * onScore.invoke({ points: 100 });
+ * ```
+ *
  * @category Events
  * @group Utilities
+ * @see {@link CallInfo} for individual callback configuration
+ * @see {@link Button} for UI button events
  */
 export class EventList<TArgs extends any = any> implements IEventList {
 

package/src/engine-components/EventTrigger.ts

@@ -12,7 +12,7 @@ class TriggerEvent {
 }
 
 /**
- * The EventTrigger component is used to trigger events when certain pointer events occur on the GameObject.
+ * The [EventTrigger](https://engine.needle.tools/docs/api/EventTrigger) component is used to trigger events when certain pointer events occur on the GameObject.
  * It implements the {@link IPointerEventHandler} interface and can be used to expose events to the user in the editor without writing code.
  * 
  * @summary Triggers events on pointer interactions

package/src/engine-components/Fog.ts

@@ -4,15 +4,37 @@ import { serializable } from "../engine/engine_serialization.js";
 import { Behaviour } from "./Component.js";
 
 
+/**
+ * Fog rendering mode
+ */
 enum FogMode {
+    /** Linear fog increases uniformly with distance */
     Linear = 1,
+    /** Exponential fog increases exponentially with distance */
     Exponential = 2,
+    /** Exponential squared fog for denser falloff */
     ExponentialSquared = 3,
 }
 
-/** @internal */
+/**
+ * Adds distance-based fog effect to the scene.  
+ * When enabled, objects will fade into the fog color based on their distance from the camera.    
+ * 
+ * This component is automatically added to the scene when fog is enabled in the editor.   
+ * For setting fog from code you can simply use `scene.fog = new Fog3(color, near, far)` without adding this component.
+ *
+ * @summary Adds fog effect to the scene
+ * @category Rendering
+ * @group Components
+ * @link https://threejs.org/docs/#Fog
+ */
 export class Fog extends Behaviour {
 
+    /**
+     * The underlying Three.js Fog object. You can modify its properties directly for more advanced control.
+     * @remarks The Fog component provides convenient access to common fog properties like `near`, `far`, and `color`. Modifying those will update the underlying `fog` object accordingly. However, you can also access and modify the `fog` object directly for more advanced use cases, such as changing the fog mode or using a custom shader.  
+     * @link https://threejs.org/docs/#Fog for available properties and methods on the Fog object.
+     */
     get fog() {
         if (!this._fog) this._fog = new Fog3(0x000000, 0, 50);
         return this._fog;