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

package/src/engine-components/SyncedTransform.ts

@@ -55,12 +55,48 @@ onUpdate((ctx) => {
 })
 
 /**
- * SyncedTransform synchronizes the position and rotation of a game object over the network.
- * It handles ownership transfer, interpolation, and network state updates automatically.
- * 
+ * SyncedTransform synchronizes position and rotation of a GameObject across the network.
+ * When users interact with an object (e.g., via {@link DragControls}), they automatically
+ * take ownership and their changes are broadcast to other users.
+ *
+ * **Features:**
+ * - Automatic ownership transfer when interacting
+ * - Smooth interpolation of remote updates
+ * - Physics integration (can override kinematic state)
+ * - Fast mode for rapidly moving objects
+ *
+ * **Requirements:**
+ * - Active network connection via {@link SyncedRoom}
+ * - Objects must have unique GUIDs (set automatically in Unity/Blender export)
+ *
+ * **Ownership:**
+ * This component uses {@link OwnershipModel} internally to manage object ownership.
+ * Only the client that owns an object can send transform updates. Use `requestOwnership()`
+ * before modifying the transform, or check `hasOwnership()` to see if you can modify it.
+ *
+ * **Debug:** Use `?debugsync` URL parameter for logging.
+ *
+ * @example Basic networked object
+ * ```ts
+ * // Add to any object you want synced
+ * const sync = myObject.addComponent(SyncedTransform);
+ * sync.fastMode = true; // For fast-moving objects
+ *
+ * // Request ownership before modifying
+ * sync.requestOwnership();
+ * myObject.position.x += 1;
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
+ *
  * @summary Synchronizes object transform over the network with ownership management
  * @category Networking
  * @group Components
+ * @see {@link SyncedRoom} for room/session management
+ * @see {@link OwnershipModel} for ownership management details
+ * @see {@link DragControls} for interactive dragging with sync
+ * @see {@link Duplicatable} for networked object spawning
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class SyncedTransform extends Behaviour {
 
@@ -94,9 +130,18 @@ export class SyncedTransform extends Behaviour {
     private _receivedFastUpdate: boolean = false;
     private _shouldRequestOwnership: boolean = false;
 
-    /** 
+    /**
      * Requests ownership of this object on the network.
      * You need to be connected to a room for this to work.
+     * Call this before modifying the object's transform to ensure your changes are synchronized.
+     *
+     * @example
+     * ```ts
+     * // Request ownership before modifying
+     * syncedTransform.requestOwnership();
+     * this.gameObject.position.y += 1;
+     * ```
+     * @see {@link OwnershipModel.requestOwnership} for more details
      */
     public requestOwnership() {
         if (debug)
@@ -110,25 +155,29 @@ export class SyncedTransform extends Behaviour {
     }
 
     /**
-     * Free ownership of this object on the network.  
-     * You need to be connected to a room for this to work.  
+     * Free ownership of this object on the network.
+     * You need to be connected to a room for this to work.
      * This will also be called automatically when the component is disabled.
+     * Call this when you're done modifying an object to allow other users to interact with it.
+     * @see {@link OwnershipModel.freeOwnership} for more details
      */
     public freeOwnership() {
         this._model?.freeOwnership();
     }
 
     /**
-     * Checks if this client has ownership of the object
-     * @returns true if this client has ownership, false if not, undefined if ownership state is unknown
+     * Checks if this client has ownership of the object.
+     * @returns `true` if this client has ownership, `false` if not, `undefined` if ownership state is unknown
+     * @see {@link OwnershipModel.hasOwnership} for more details
      */
     public hasOwnership(): boolean | undefined {
         return this._model?.hasOwnership ?? undefined;
     }
 
     /**
-     * Checks if the object is owned by any client
-     * @returns true if the object is owned, false if not, undefined if ownership state is unknown
+     * Checks if the object is owned by any client (local or remote).
+     * @returns `true` if the object is owned, `false` if not, `undefined` if ownership state is unknown
+     * @see {@link OwnershipModel.isOwned} for more details
      */
     public isOwned(): boolean | undefined {
         return this._model?.isOwned;

package/src/engine-components/TransformGizmo.ts

@@ -8,12 +8,39 @@ import { OrbitControls } from "./OrbitControls.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 
 /**
- * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
- * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
- * 
- * @summary Object manipulation gizmo for translating, rotating, and scaling
+ * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects.  
+ * Wraps three.js {@link TransformControls} with keyboard shortcuts and snapping support.  
+ *
+ * **Keyboard shortcuts:**
+ * - `W` - Translate mode
+ * - `E` - Rotate mode
+ * - `R` - Scale mode
+ * - `Q` - Toggle local/world space
+ * - `Shift` (hold) - Enable grid snapping
+ * - `+/-` - Adjust gizmo size
+ * - `X/Y/Z` - Toggle axis visibility
+ * - `Space` - Toggle controls enabled
+ *
+ * **Snapping:**
+ * Configure grid snapping with `translationSnap`, `rotationSnapAngle`, and `scaleSnap`.
+ *
+ * **Networking:**
+ * Automatically works with {@link SyncedTransform} for multiplayer editing.
+ *
+ * @example Add transform gizmo to an object
+ * ```ts
+ * const gizmo = editableObject.addComponent(TransformGizmo);
+ * gizmo.translationSnap = 0.5; // Snap to 0.5 unit grid
+ * gizmo.rotationSnapAngle = 45; // Snap to 45° increments
+ * ```
+ *
+ * @summary Object manipulation gizmo for translate/rotate/scale
  * @category Helpers
  * @group Components
+ * @see {@link DragControls} for simpler drag-only interaction
+ * @see {@link SyncedTransform} for network synchronization
+ * @see {@link OrbitControls} - automatically disabled during gizmo drag
+ * @link https://threejs.org/docs/index.html#examples/en/controls/TransformControls for underlying three.js controls and additional features
  */
 export class TransformGizmo extends Behaviour {
 

package/src/engine-components/VideoPlayer.ts

@@ -9,6 +9,7 @@ import { getWorldScale } from "../engine/engine_three_utils.js";
 import { getParam } from "../engine/engine_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 import { Renderer } from "./Renderer.js";
+import { PointerEventData } from "./api.js";
 
 const debug = getParam("debugvideo");
 
@@ -45,18 +46,45 @@ export enum VideoRenderMode {
 }
 
 /**
- * The VideoPlayer component can be used to playback video clips from urls, streams or m3u8 playlists (livestreams)
- * @example Add a video player component to a game object and set the url to a video file. The video will start playing once the object becomes active in your scene
- * ```typescript
- * // Add a video player component to a game object and set the url to a video file. The video will start playing once the object becomes active in your scene
+ * VideoPlayer plays video clips from URLs, media streams, or HLS playlists (m3u8 livestreams).  
+ *
+ * **Supported formats:**  
+ * - Standard video files (MP4, WebM, etc.)
+ * - Media streams (from webcam, screen capture, etc.)
+ * - HLS playlists (m3u8) for livestreaming  
+ * 
+ * ![](https://cloud.needle.tools/-/media/w1uHur5yu3Ni7qFaKIFX-g.gif)
+ *
+ * **Rendering modes:**  
+ * Video can be rendered to a material texture, render texture, or camera planes.  
+ * Set `targetMaterialRenderer` to apply video to a specific mesh's material.  
+ *
+ * **Browser autoplay:**  
+ * Videos may require user interaction to play with audio.  
+ * Set `playOnAwake = true` for automatic playback (muted if needed).  
+ *
+ * @example Basic video playback
+ * ```ts
  * const videoPlayer = addComponent(obj, VideoPlayer, {
- *    url: "https://www.w3schools.com/html/mov_bbb.mp4",
- *    playOnAwake: true,
+ *   url: "https://example.com/video.mp4",
+ *   playOnAwake: true,
+ *   loop: true,
  * });
  * ```
+ *
+ * @example Play video on a 3D surface
+ * ```ts
+ * const video = myScreen.getComponent(VideoPlayer);
+ * video.targetMaterialRenderer = myScreen.getComponent(Renderer);
+ * video.play();
+ * ```
+ *
  * @summary Plays video clips from URLs or streams
  * @category Multimedia
  * @group Components
+ * @see {@link AudioSource} for audio-only playback
+ * @see {@link ScreenCapture} for capturing and sharing video
+ * @see {@link Renderer} for video texture targets
  */
 export class VideoPlayer extends Behaviour {
 
@@ -72,6 +100,20 @@ export class VideoPlayer extends Behaviour {
     @serializable()
     aspectMode: AspectMode = AspectMode.None;
 
+    // /**
+    //  * If true the video will toggle between play and pause when clicked.   
+    //  * Note that this requires the video element to be interactable which is not the case when using certain render modes like CameraNearPlane or CameraFarPlane. In those cases you can use the `requestPictureInPicture()` method to open the video in a separate window which allows interaction with the video element.
+    //  */
+    // @serializable()
+    // clickToToggle: boolean = true;
+
+    // onPointerClick(_args: PointerEventData) {
+    //     if (this.clickToToggle) {
+    //         if (this.isPlaying) this.pause();
+    //         else this.play();
+    //     }
+    // }
+
     @serializable(URL)
     private clip?: string | MediaStream | null = null;
 

package/src/engine-components/Voip.ts

@@ -12,11 +12,42 @@ export const noVoip = "noVoip";
 const debugParam = getParam("debugvoip");
 
 /**
- * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
- * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
+ * Voice over IP (VoIP) component for real-time audio communication between users.  
+ * Allows sending and receiving audio streams in networked rooms.  
+ *
+ * **Requirements:**  
+ * - Active network connection (via {@link SyncedRoom} or manual connection)  
+ * - User permission for microphone access (requested automatically)  
+ * - HTTPS connection (required for WebRTC)  
+ *
+ * **Features:**  
+ * - Automatic connection when joining rooms (`autoConnect`)  
+ * - Background audio support (`runInBackground`)  
+ * - Optional UI toggle button (`createMenuButton`)  
+ * - Mute/unmute control  
+ *
+ * **Debug:** Use `?debugvoip` URL parameter or set `debug = true` for logging.  
+ * Press 'v' to toggle mute, 'c' to connect/disconnect when debugging.  
+ *
+ * @example Enable VoIP in your scene
+ * ```ts
+ * const voip = myObject.addComponent(Voip);
+ * voip.autoConnect = true;
+ * voip.createMenuButton = true;
+ *
+ * // Manual control
+ * voip.connect();    // Start sending audio
+ * voip.disconnect(); // Stop sending
+ * voip.setMuted(true); // Mute microphone
+ * ```
+ *
  * @summary Voice over IP for networked audio communication
  * @category Networking
  * @group Components
+ * @see {@link SyncedRoom} for room management
+ * @see {@link NetworkedStreams} for the underlying streaming
+ * @see {@link ScreenCapture} for video streaming
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class Voip extends Behaviour {
 

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -71,22 +71,56 @@ type BeforeLODExportArguments = {
 }
 
 /**
- * Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.  
- * The USDZ file is generated using the Needle Engine ThreeUSDZExporter.  
- * The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.  
- * The exporter can automatically collect Animations and AudioSources and export them as playing at the start.  
- * The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.  
- * @example
- * ```typescript
- * const usdz = new USDZExporter();
- * usdz.objectToExport = myObject;
- * usdz.autoExportAnimations = true;
- * usdz.autoExportAudioSources = true;
- * usdz.exportAsync();
+ * USDZExporter creates USDZ files and opens them in Apple QuickLook on iOS/iPadOS/visionOS.  
+ * Enables "View in AR" functionality for Apple devices directly from web experiences.  
+ *
+ * **Key features:**  
+ * - Auto-exports animations and audio sources  
+ * - Interactive behaviors via Needle's "Everywhere Actions" system  
+ * - RealityKit physics support (iOS 18+, visionOS 1+)
+ * - Custom QuickLook overlay with call-to-action buttons
+ * - Progressive texture/mesh LOD handling
+ * 
+ * [![](https://cloud.needle.tools/-/media/YyUz1lUVlOhEY4fWZ-oMsA.gif)](https://engine.needle.tools/samples/?overlay=samples&tag=usdz)
+ *
+ * **Automatic setup:**  
+ * - Creates QuickLook button on compatible devices
+ * - Respects {@link XRFlag} for AR-specific visibility
+ * - Handles {@link WebARSessionRoot} scale
+ *
+ * **Custom extensions:**  
+ * Add custom behaviors by implementing {@link IUSDExporterExtension} and adding to {@link extensions} array.  
+ * 
+ * **Debug:** Use `?debugusdz` URL parameter. Press 'T' to trigger export.  
+ *
+ * @example Basic USDZ export  
+ * ```ts
+ * const exporter = myObject.addComponent(USDZExporter);
+ * exporter.objectToExport = productModel;
+ * exporter.autoExportAnimations = true;
+ * exporter.interactive = true; // Enable QuickLook behaviors
+ *
+ * // Trigger export
+ * await exporter.exportAndOpen();
  * ```
- * @summary Export 3D objects as USDZ files for QuickLook
+ *
+ * @example Custom branding  
+ * ```ts
+ * exporter.customBranding = {
+ *   callToAction: "Buy Now",
+ *   checkoutTitle: "Product Name",
+ *   callToActionURL: "https://shop.example.com"
+ * };
+ * ```
+ *
+ * @summary Export 3D objects as USDZ files for Apple QuickLook AR
  * @category XR
  * @group Components
+ * @see {@link WebXR} for WebXR-based AR/VR
+ * @see {@link WebARSessionRoot} for AR placement and scaling
+ * @see {@link XRFlag} for AR-specific object visibility
+ * @see {@link CustomBranding} for QuickLook overlay customization  
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=usdz
  */
 export class USDZExporter extends Behaviour {
 

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -24,11 +24,20 @@ const debugProgressiveLoading = getParam("debugprogressive");
 
 export type { Particle as QParticle, Behavior as QParticleBehaviour, TrailParticle as QTrailParticle } from "three.quarks"
 
+/**
+ * Defines when a sub-emitter spawns particles relative to the parent particle's lifecycle.  
+ * Used to create complex effects like explosions on impact or trails following particles.  
+ */
 export enum SubEmitterType {
+    /** Sub-emitter triggers when the parent particle is born */
     Birth = 0,
+    /** Sub-emitter triggers when the parent particle collides */
     Collision = 1,
+    /** Sub-emitter triggers when the parent particle dies */
     Death = 2,
+    /** Sub-emitter triggers when the parent particle enters a trigger zone */
     Trigger = 3,
+    /** Sub-emitter is triggered manually via code */
     Manual = 4,
 }
 
@@ -274,9 +283,33 @@ class ParticleSystemEmissionOverDistance extends BaseValueGenerator {
     }
 }
 
+/**
+ * Base class for custom particle behaviors. Extend this to create custom particle logic.  
+ *
+ * Override `initialize()` to set up per-particle state when particles spawn.  
+ * Override `update()` to modify particles each frame (position, velocity, color, size, etc.).  
+ * Override `frameUpdate()` for logic that runs once per frame (not per particle).  
+ *
+ * @example Custom wind effect
+ * ```ts
+ * class WindBehaviour extends ParticleSystemBaseBehaviour {
+ *   windStrength = 2;
+ *   windDirection = new Vector3(1, 0, 0);
+ *
+ *   update(particle: Particle, delta: number) {
+ *     particle.velocity.addScaledVector(this.windDirection, this.windStrength * delta);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link ParticleSystem.addBehaviour} to register your custom behavior
+ * @link https://github.com/Alchemist0823/three.quarks
+ */
 export abstract class ParticleSystemBaseBehaviour implements Behavior {
 
+    /** Reference to the particle system this behavior belongs to */
     system!: ParticleSystem;
+    /** Access to the engine context for timing, input, etc. */
     get context() { return this.system.context; }
 
     constructor(ps?: ParticleSystem) {
@@ -285,13 +318,18 @@ export abstract class ParticleSystemBaseBehaviour implements Behavior {
             this.system = ps;
     }
 
+    /** Behavior type identifier used by three.quarks */
     type: string;
 
+    /** Called once when a particle is spawned. Use to initialize per-particle state. */
     initialize(_particle: Particle): void { }
+    /** Called every frame for each active particle. Use to update particle properties. */
     update(_particle: Particle, _delta: number): void { }
+    /** Called once per frame before particle updates. Use for shared calculations. */
     frameUpdate(_delta: number): void { }
     toJSON() { throw new Error("Method not implemented."); }
     clone(): Behavior { throw new Error("Method not implemented."); }
+    /** Called when the particle system is reset. */
     reset() { }
 }
 
@@ -686,15 +724,56 @@ class ParticlesEmissionState implements EmissionState {
 }
 
 /**
- * The ParticleSystem component efficiently handles the motion and rendering of many individual particles.    
- * 
- * You can add custom behaviours to the particle system to fully customize the behaviour of the particles. See {@link ParticleSystemBaseBehaviour} and {@link ParticleSystem.addBehaviour} for more information.
- * 
- * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
+ * ParticleSystem efficiently handles the motion and rendering of many individual particles.  
+ * Use it for visual effects like fire, smoke, sparks, rain, magic spells, and more.  
  * 
+ * ![](https://cloud.needle.tools/-/media/qz5nO-raa7dNb_XCBNxHmA.gif)  
+ * ![](https://cloud.needle.tools/-/media/IKOrLhesy1dKTfQQxx_pLA.gif)
+ *
+ * **Modules:**
+ * Configure particle behavior through modules like {@link EmissionModule}, {@link ShapeModule},
+ * {@link ColorOverLifetimeModule}, {@link SizeOverLifetimeModule}, {@link VelocityOverLifetimeModule},
+ * {@link NoiseModule}, and {@link TrailModule}.
+ *
+ * **Custom behaviors:**  
+ * Add custom particle behaviors by extending {@link ParticleSystemBaseBehaviour} and  
+ * calling `addBehaviour()`. This gives you full control over particle initialization and updates.  
+ *
+ * **Performance:**  
+ * Particles are batched together for fast, performant rendering even on low-end devices.  
+ * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) internally.  
+ *
+ * @example Basic playback control
+ * ```ts
+ * const ps = myObject.getComponent(ParticleSystem);
+ * ps.play();
+ * ps.emit(10); // Emit 10 particles immediately
+ * ps.pause();
+ * ps.stop(true, true); // Stop and clear all particles
+ * ```
+ *
+ * @example Custom particle behavior
+ * ```ts
+ * class GravityBehaviour extends ParticleSystemBaseBehaviour {
+ *   update(particle: Particle, delta: number) {
+ *     particle.velocity.y -= 9.8 * delta;
+ *   }
+ * }
+ * particleSystem.addBehaviour(new GravityBehaviour());
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/particles
+ * - Example: https://engine.needle.tools/samples/particle-bursts
+ * - Example: https://engine.needle.tools/samples/particles-on-collision
+ *
  * @summary Handles the motion and rendering of many individual particles
  * @category Rendering
  * @group Components
+ * @see {@link ParticleSystemBaseBehaviour} for custom particle behaviors
+ * @see {@link EmissionModule} for emission configuration
+ * @see {@link ShapeModule} for emission shape control
+ * @see {@link TrailModule} for particle trails
+ * @link https://engine.needle.tools/docs/features/particles.html
  */
 export class ParticleSystem extends Behaviour implements IParticleSystem {