@needle-tools/engine 4.13.0 → 4.13.1-beta

package/src/engine-components/VideoPlayer.ts

@@ -7,6 +7,7 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Context } from "../engine/engine_setup.js";
 import { getWorldScale } from "../engine/engine_three_utils.js";
 import { getParam } from "../engine/engine_utils.js";
+import { PointerEventData } from "./api.js";
 import { Behaviour, GameObject } from "./Component.js";
 import { Renderer } from "./Renderer.js";
 
@@ -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](https://engine.needle.tools/docs/api/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).  
+ * [Voip](https://engine.needle.tools/docs/api/Voip) 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 {
 

package/src/engine-components/postprocessing/Effects/Antialiasing.ts

@@ -17,6 +17,7 @@ export enum QualityLevel {
 }
 
 /**
+ * [Antialiasing](https://engine.needle.tools/docs/api/Antialiasing) provides SMAA (Subpixel Morphological Antialiasing) post-processing effect to smooth edges in the rendered scene.
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/BloomEffect.ts

@@ -8,7 +8,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Bloom can be used to make bright areas in the scene glow.  
+ * [BloomEffect](https://engine.needle.tools/docs/api/BloomEffect) can be used to make bright areas in the scene glow.  
  * @link Sample https://engine.needle.tools/samples/postprocessing
  * @example
  * ```typescript

package/src/engine-components/postprocessing/Effects/ChromaticAberration.ts

@@ -7,7 +7,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType, VolumeProfile } from "../VolumeProfile.js";
 
 /**
- * Chromatic Aberration effect simulates the color fringing effect seen in real-world cameras.  
+ * [ChromaticAberration](https://engine.needle.tools/docs/api/ChromaticAberration) simulates the color fringing effect seen in real-world cameras.  
  * It offsets the red, green, and blue color channels to create a distorted, colorful edge around objects.  
  * This effect can enhance the visual appeal of scenes by adding a subtle or pronounced chromatic distortion.
  * @summary Chromatic Aberration Post-Processing Effect

package/src/engine-components/postprocessing/Effects/ColorAdjustments.ts

@@ -8,7 +8,7 @@ import { registerCustomEffectType } from "../VolumeProfile.js";
 import { ToneMappingEffect } from "./Tonemapping.js";
 
 /**
- * Color Adjustments effect allows you to modify the overall color properties of the rendered scene, including post-exposure, contrast, hue shift, and saturation.  
+ * [ColorAdjustments](https://engine.needle.tools/docs/api/ColorAdjustments) allows you to modify the overall color properties of the rendered scene, including post-exposure, contrast, hue shift, and saturation.  
  * These adjustments can be used to enhance the visual aesthetics of the scene or to achieve specific artistic effects.
  * @summary Color Adjustments Post-Processing Effect
  * @category Effects

package/src/engine-components/postprocessing/Effects/DepthOfField.ts

@@ -17,7 +17,7 @@ export enum DepthOfFieldMode {
 const debug = getParam("debugpost");
 
 /**
- * Depth of Field effect simulates the focusing behavior of real-world cameras by blurring objects that are outside the focal plane.  
+ * [DepthOfField](https://engine.needle.tools/docs/api/DepthOfField) simulates the focusing behavior of real-world cameras by blurring objects that are outside the focal plane.  
  * This effect enhances the sense of depth in a scene by mimicking how cameras focus on subjects at varying distances, creating a more immersive visual experience.  
  * It can be adjusted to achieve different artistic effects, from subtle background blurring to pronounced bokeh effects.
  * @summary Depth of Field Post-Processing Effect

package/src/engine-components/postprocessing/Effects/EffectWrapper.ts

@@ -3,6 +3,7 @@ import type { Effect } from "postprocessing";
 import { EffectProviderResult, PostProcessingEffect } from "../PostProcessingEffect.js";
 
 /**
+ * [EffectWrapper](https://engine.needle.tools/docs/api/EffectWrapper) wraps a custom postprocessing effect to integrate it with the Needle Engine post-processing pipeline.
  *
  * @category Effects
  * @group Components

package/src/engine-components/postprocessing/Effects/Pixelation.ts

@@ -7,7 +7,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Pixelation effect simulates a pixelated look by enlarging pixels in the rendered scene.  
+ * [PixelationEffect](https://engine.needle.tools/docs/api/PixelationEffect) Pixelation effect simulates a pixelated look by enlarging pixels in the rendered scene.  
  * This effect can be used to achieve a retro or stylized visual aesthetic, reminiscent of early video games or low-resolution graphics.
  * @summary Pixelation Post-Processing Effect
  * @category Effects

package/src/engine-components/postprocessing/Effects/ScreenspaceAmbientOcclusion.ts

@@ -7,7 +7,7 @@ import { type EffectProviderResult, PostProcessingEffect } from "../PostProcessi
 import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
-/** Screenspace Ambient Occlusion post-processing effect.  
+/** [ScreenSpaceAmbientOcclusion](https://engine.needle.tools/docs/api/ScreenSpaceAmbientOcclusion) is a screenspace ambient occlusion post-processing effect.  
  * We recommend using ScreenSpaceAmbientOcclusionN8 instead.  
  * @category Effects
  * @group Components

package/src/engine-components/postprocessing/Effects/ScreenspaceAmbientOcclusionN8.ts

@@ -22,7 +22,7 @@ export enum ScreenSpaceAmbientOcclusionN8QualityMode {
     Ultra = 4,
 }
 
-/** Screen Space Ambient Occlusion (SSAO) effect.  
+/** [ScreenSpaceAmbientOcclusionN8](https://engine.needle.tools/docs/api/ScreenSpaceAmbientOcclusionN8) is a screen space ambient occlusion (SSAO) effect.
  * Ambient Occlusion is a shading method used to calculate how exposed each point in a scene is to ambient lighting.  
  * The effect enhances the depth and realism of 3D scenes by simulating the soft shadows that occur in crevices, corners, and areas where objects are close to each other.  
  * This implementation uses the N8AO library to provide high-quality SSAO with various quality settings.

package/src/engine-components/postprocessing/Effects/Sharpening.ts

@@ -14,7 +14,7 @@ import { PostProcessingEffectOrder } from "../utils.js";
 // }
 
 /**
- * Sharpening effect enhances the details and edges in the rendered scene by increasing the contrast between adjacent pixels.
+ * [SharpeningEffect](https://engine.needle.tools/docs/api/SharpeningEffect) Sharpening effect enhances the details and edges in the rendered scene by increasing the contrast between adjacent pixels.
  * This effect can make textures and fine details appear clearer and more defined, improving the overall visual quality of the scene.  
  * It is particularly useful in scenes where details may be lost due to blurriness or low resolution.
  * @summary Sharpening Post-Processing Effect

package/src/engine-components/postprocessing/Effects/TiltShiftEffect.ts

@@ -5,7 +5,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Tilt Shift effect simulates a miniature scene by applying a selective focus blur to the rendered image.  
+ * [TiltShiftEffect](https://engine.needle.tools/docs/api/TiltShiftEffect) Tilt Shift effect simulates a miniature scene by applying a selective focus blur to the rendered image.  
  * This effect creates a shallow depth of field, making real-world scenes appear as if they are small-scale models.  
  * It is often used in photography and cinematography to draw attention to specific areas of the scene while blurring out the rest.
  * @summary Tilt Shift Post-Processing Effect

package/src/engine-components/postprocessing/Effects/Tonemapping.ts

@@ -14,7 +14,7 @@ const debug = getParam("debugpost");
 
 
 /**
- * Tonemapping effect adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.  
+ * [ToneMappingEffect](https://engine.needle.tools/docs/api/ToneMappingEffect) adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.  
  * This effect is essential for achieving realistic lighting and color representation in 3D scenes, as it helps to preserve details in both bright and dark areas.  
  * Various tonemapping algorithms can be applied to achieve different visual styles and effects.
  * @summary Tonemapping Post-Processing Effect

package/src/engine-components/postprocessing/Effects/Vignette.ts

@@ -7,7 +7,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Vignette effect darkens the edges of the rendered scene to draw attention to the center.  
+ * [Vignette](https://engine.needle.tools/docs/api/Vignette) darkens the edges of the rendered scene to draw attention to the center.  
  * This effect simulates the natural vignetting that occurs in photography and cinematography, where the corners of an image are darker than the center.  
  * It can be used to enhance the visual focus on the main subject of the scene and create a more immersive viewing experience.
  * @summary Vignette Post-Processing Effect

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -24,7 +24,7 @@ const autoclearSetting = Symbol("needle:previous-autoclear-state");
 const previousToneMapping = Symbol("needle:previous-tone-mapping");
 
 /**
- * PostProcessingHandler is responsible for applying post processing effects to the scene. It is internally used by the {@link Volume} component
+ * [PostProcessingHandler](https://engine.needle.tools/docs/api/PostProcessingHandler) Is responsible for applying post processing effects to the scene. It is internally used by the {@link Volume} component
  */
 export class PostProcessingHandler {
 

package/src/engine-components/postprocessing/Volume.ts

@@ -16,7 +16,7 @@ import { VolumeProfile } from "./VolumeProfile.js";
 const debug = getParam("debugpost");
 
 
-/** The Volume/PostprocessingManager component is responsible for managing post processing effects.  
+/** [Volume](https://engine.needle.tools/docs/api/Volume) The Volume/PostprocessingManager component is responsible for managing post processing effects.  
  * Add this component to any object in your scene to enable post processing effects.  
  * 
  * @example Add bloom