@needle-tools/engine 4.13.0 → 4.13.1-next.6cb1b73

package/src/engine-components/AxesHelper.ts

@@ -5,12 +5,31 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * Component that visualizes the axes of an object in the scene.
- * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
- * 
- * @summary Visualizes object axes in the scene
+ * The [AxesHelper](https://engine.needle.tools/docs/api/AxesHelper) visualizes the local coordinate axes of an object.
+ * Displays colored lines for X (red), Y (green), and Z (blue) axes.
+ *
+ * **Use cases:**
+ * - Debugging object orientation and rotation
+ * - Visualizing pivot points
+ * - Understanding coordinate systems
+ *
+ * **Properties:**
+ * - `length` - Length of axis lines in world units
+ * - `depthTest` - Whether axes are occluded by scene objects
+ * - `isGizmo` - Only show when `?gizmos` URL parameter is set
+ *
+ * @example Add axes visualization
+ * ```ts
+ * const axes = myObject.addComponent(AxesHelper);
+ * axes.length = 2;
+ * axes.depthTest = false; // Always visible on top
+ * ```
+ *
+ * @summary Visualizes object axes (X=red, Y=green, Z=blue)
  * @category Helpers
  * @group Components
+ * @see {@link GridHelper} for grid visualization
+ * @see {@link Gizmos} for debug drawing utilities
  */
 export class AxesHelper extends Behaviour {
     /**

package/src/engine-components/BasicIKConstraint.ts

@@ -4,12 +4,35 @@ import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.  
- * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
- * 
- * @summary Simple Inverse Kinematics Constraint
- * @category Animation
+ * The [BasicIKConstraint](https://engine.needle.tools/docs/api/BasicIKConstraint) provides simple two-bone inverse kinematics.
+ * Positions this GameObject as a "joint" between `from` and `to` targets,
+ * using a `hint` object to determine the bend direction.
+ *
+ * **Use cases:**
+ * - Simple arm/leg IK (elbow/knee positioning)
+ * - Mechanical linkages
+ * - Procedural animation joints
+ *
+ * **How it works:**
+ * - Calculates joint position based on `desiredDistance` (bone length)
+ * - Uses `hint` to determine which way the joint bends
+ * - Automatically handles stretching when targets are too far apart
+ *
+ * @example Setup basic limb IK
+ * ```ts
+ * // Attach to the elbow/knee joint object
+ * const ik = elbowJoint.addComponent(BasicIKConstraint);
+ * // Configure via serialized properties in editor:
+ * // - from: shoulder/hip
+ * // - to: wrist/ankle
+ * // - hint: control point for bend direction
+ * ```
+ *
+ * @summary Two-bone inverse kinematics constraint
+ * @category Animation and Sequencing
  * @group Components
+ * @see {@link LookAtConstraint} for aim constraints
+ * @see {@link AlignmentConstraint} for simpler alignment
  */
 export class BasicIKConstraint extends Behaviour {
 

package/src/engine-components/Camera.ts

@@ -32,13 +32,43 @@ const debug = getParam("debugcam");
 const debugscreenpointtoray = getParam("debugscreenpointtoray");
 
 /**
- * Camera component that handles rendering from a specific viewpoint in the scene.
- * Supports both perspective and orthographic cameras with various rendering options.
- * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
+ * [Camera](https://engine.needle.tools/docs/api/Camera) handles rendering from a specific viewpoint in the scene.  
+ * Supports both perspective and orthographic cameras with various rendering options.  
+ * Internally uses three.js {@link PerspectiveCamera} or {@link OrthographicCamera}.    
  * 
+ * ![](https://cloud.needle.tools/-/media/UU96_SJNXdVjaAvPNW3kZA.webp)
+ *
+ * **Background clearing:**  
+ * Control how the camera clears the background using `clearFlags`:  
+ * - `Skybox` - Use scene skybox/environment
+ * - `SolidColor` - Clear with `backgroundColor`
+ * - `None` - Don't clear (for layered rendering)
+ *
+ * **Render targets:**  
+ * Set `targetTexture` to a {@link RenderTexture} to render to a texture  
+ * instead of the screen (useful for mirrors, portals, minimaps).  
+ * 
+ * [![](https://cloud.needle.tools/-/media/W4tYZuJVVJFVp7NTaHPOnA.gif)](https://engine.needle.tools/samples/movie-set)
+ *
+ * @example Configure camera settings
+ * ```ts
+ * const cam = this.context.mainCameraComponent;
+ * cam.fieldOfView = 60;
+ * cam.nearClipPlane = 0.1;
+ * cam.farClipPlane = 1000;
+ * cam.clearFlags = ClearFlags.SolidColor;
+ * cam.backgroundColor = new RGBAColor(0.1, 0.1, 0.2, 1);
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/multiple-cameras
+ *
  * @summary Rendering scenes from a specific viewpoint
  * @category Camera and Controls
  * @group Components
+ * @see {@link OrbitControls} for camera interaction
+ * @see {@link RenderTexture} for off-screen rendering
+ * @see {@link ClearFlags} for background clearing options
+ * @link https://engine.needle.tools/samples/movie-set/
  */
 export class Camera extends Behaviour implements ICamera {
 

package/src/engine-components/CharacterController.ts

@@ -14,18 +14,49 @@ import { Rigidbody } from "./RigidBody.js";
 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.
+ * The [CharacterController](https://engine.needle.tools/docs/api/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.  
+ *
+ * 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

@@ -13,6 +13,9 @@ import { HideFlags, IGameObject, Vec3 } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js"
 import { setCustomVisibility } from "../engine/js-extensions/Layers.js";
 import { Behaviour, GameObject } from "./Component.js";
+import type { Light } from "./Light.js";
+import type { Renderer } from "./Renderer.js";
+import type { ShadowCatcher } from "./ShadowCatcher.js";
 
 const debug = getParam("debugcontactshadows");
 
@@ -44,19 +47,40 @@ 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.  
+ * Produces soft, blurred shadows that hug the ground, giving a sense of contact and depth.     
  * 
+ * ![](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 ShadowCatcher} for real-time shadows from lights (more accurate, higher performance cost)
+ * @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 +185,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 +283,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 +401,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 {