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

package/src/engine/engine_utils.ts

@@ -111,11 +111,27 @@ export function getUrlParams() {
 // bit strange that we have to pass T in here as well but otherwise the type parameter is stripped it seems
 type Param<T extends string> = string | boolean | number | T;
 
-/** Checks if a url parameter exists.
- * Returns true if it exists but has no value (e.g. ?help)
- * Returns false if it does not exist
- * Returns false if it's set to 0 e.g. ?debug=0
- * Returns the value if it exists e.g. ?message=hello
+/**
+ * Checks if a URL parameter exists and returns its value.  
+ * Useful for debugging, feature flags, and configuration.  
+ *
+ * @param paramName The URL parameter name to check
+ * @returns
+ * - `true` if the parameter exists without a value (e.g. `?debug`)
+ * - `false` if the parameter doesn't exist or is set to `0`
+ * - The numeric value if it's a number (e.g. `?level=5` returns `5`)
+ * - The string value otherwise (e.g. `?name=test` returns `"test"`)
+ *
+ * @example Check debug mode
+ * ```ts
+ * if (getParam("debug")) {
+ *   console.log("Debug mode enabled");
+ * }
+ * ```
+ * @example Get a numeric value
+ * ```ts
+ * const level = getParam("level"); // Returns number if ?level=5
+ * ```
  */
 export function getParam<T extends string>(paramName: T): Param<T> {
     if (showHelp && !requestedParams.includes(paramName))
@@ -573,6 +589,7 @@ declare global {
 
 /**
  * Utility functions to detect certain device types (mobile, desktop), browsers, or capabilities.
+ * @category Utilities
  */
 export namespace DeviceUtilities {
 

package/src/engine/engine_utils_screenshot.ts

@@ -32,6 +32,7 @@ declare type ScreenshotImageMimeType = "image/webp" | "image/png" | "image/jpeg"
  * const dataUrl = screenshot();
  * saveImage(dataUrl, "screenshot.png");
  * ```
+ * 
  */
 export function screenshot(context?: Context, width?: number, height?: number, mimeType: ScreenshotImageMimeType = "image/webp", camera?: Camera | null): string | null {
     return screenshot2({ context, width, height, mimeType, camera });
@@ -106,12 +107,30 @@ export declare type ScreenshotOptionsBlob = ScreenshotOptions & {
 }
 
 export declare type ScreenshotOptionsShare = ScreenshotOptions & {
+    /**
+     * Set `{ type: "share" }` to share the screenshot using the Web Share API. The promise will resolve with the blob of the screenshot and whether it was shared successfully or not. Note that the Web Share API is only available in secure contexts (HTTPS) and on some platforms.
+     */
     type: "share",
+    /**
+     * The filename to use when sharing the screenshot. If not provided, a default filename will be used.
+     */
     filename?: string,
+    /**
+     * The mime type of the shared file. If not provided, the mime type will be inferred from the screenshot options or default to "image/png".
+     */
     file_type?: ScreenshotImageMimeType,
 
+    /**
+     * The title to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+     */
     title?: string,
+    /**
+     * The text to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+     */
     text?: string,
+    /**
+     * The URL to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+     */
     url?: string,
 }
 
@@ -120,36 +139,241 @@ declare type ScreenshotOptionsShareReturnType = {
     shared: boolean,
 }
 
-/** 
- * Take a screenshot from the current scene and return a {@link Texture}. This can applied to a surface in 3D space.
- * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.
+/**
+ * Take a screenshot from the current scene and return a {@link Texture}. This can be applied to a surface in 3D space.  
+ * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.  
  * @returns The texture of the screenshot. Returns null if the screenshot could not be taken.
+ * @category Utilities
+ * @example
+ * ```ts
+ * // Create a texture from the current view
+ * const screenshotTexture = screenshot2({ type: "texture", width: 512, height: 512 });
+ * if (screenshotTexture) {
+ *   myMaterial.map = screenshotTexture;
+ *   myMaterial.needsUpdate = true;
+ * }
+ *
+ * // Update an existing texture
+ * const existingTexture = new Texture();
+ * screenshot2({ type: "texture", target: existingTexture, transparent: true });
+ * ```
  */
 export function screenshot2(opts: ScreenshotOptionsTexture): Texture | null;
+
 /**
- * Take a screenshot from the current scene.  
- * @param opts
- * @returns The data url of the screenshot. Returns null if the screenshot could not be taken.
- * ```ts	
- * const res = screenshot2({
- *    width: 1024,
+ * Take a screenshot from the current scene and return a data URL string.
+ *
+ * @param opts Screenshot options. All properties are optional.
+ * @returns The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.
+ * @category Utilities
+ *
+ * @example Basic screenshot
+ * ```ts
+ * // Take a simple screenshot with default settings
+ * const dataUrl = screenshot2({});
+ * console.log(dataUrl); // "data:image/webp;base64,..."
+ * ```
+ *
+ * @example High-resolution screenshot with transparent background
+ * ```ts
+ * const dataUrl = screenshot2({
+ *   width: 2048,
+ *   height: 2048,
+ *   mimeType: "image/png",
+ *   transparent: true,
+ *   trim: true, // Remove transparent edges
+ * });
+ * ```
+ *
+ * @example Screenshot with custom background color
+ * ```ts
+ * import { Color } from "three";
+ *
+ * const dataUrl = screenshot2({
+ *   width: 1024,
+ *   height: 1024,
+ *   background: new Color(0x00ff00), // Green background
+ * });
+ * ```
+ *
+ * @example Download screenshot automatically
+ * ```ts
+ * screenshot2({
+ *   width: 1920,
+ *   height: 1080,
+ *   mimeType: "image/jpeg",
+ *   download_filename: "my-scene.jpg",
+ * });
+ * ```
+ *
+ * @example Manual download using saveImage
+ * ```ts
+ * const dataUrl = screenshot2({
+ *   width: 1024,
+ *   height: 1024,
+ *   mimeType: "image/webp",
+ *   transparent: true,
+ * });
+ * if (dataUrl) {
+ *   saveImage(dataUrl, "screenshot.webp");
+ * }
+ * ```
+ *
+ * @example Screenshot from specific camera
+ * ```ts
+ * const myCamera = this.gameObject.getComponent(Camera);
+ * const dataUrl = screenshot2({
+ *   camera: myCamera,
+ *   width: 1024,
  *   height: 1024,
- *  mimeType: "image/webp",
- * transparent: true,
- * })
- * // use saveImage to download the image
- * saveImage(res, "screenshot.webp");
+ * });
  * ```
  */
 export function screenshot2(opts: ScreenshotOptionsDataUrl): string | null;
 
 /**
- * Take a screenshot asynchronously from the current scene.
- * @returns A promise that resolves with the blob of the screenshot. Returns null if the screenshot could not be taken.
- * @param {ScreenshotOptionsBlob} opts Set `{ type: "blob" }` to get a blob instead of a data url.
+ * Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.  
+ *
+ * @param opts Set `{ type: "blob" }` to get a blob instead of a data url. All other {@link ScreenshotOptions} are also available.  
+ * @returns A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.  
+ * @category Utilities
+ *
+ * @example Upload screenshot to server
+ * ```ts
+ * const blob = await screenshot2({ type: "blob", mimeType: "image/png" });
+ * if (blob) {
+ *   const formData = new FormData();
+ *   formData.append("screenshot", blob, "screenshot.png");
+ *   await fetch("/api/upload", { method: "POST", body: formData });
+ * }
+ * ```
+ *
+ * @example Save blob to file (browser download)
+ * ```ts
+ * const blob = await screenshot2({
+ *   type: "blob",
+ *   width: 1920,
+ *   height: 1080,
+ *   transparent: true
+ * });
+ * if (blob) {
+ *   const url = URL.createObjectURL(blob);
+ *   saveImage(url, "screenshot.png");
+ *   URL.revokeObjectURL(url); // Clean up
+ * }
+ * ```
  */
 export function screenshot2(opts: ScreenshotOptionsBlob): Promise<Blob | null>;
+
+/**
+ * Take a screenshot and share it using the Web Share API (mobile-friendly).  
+ *
+ * **Note**: The Web Share API is only available in secure contexts (HTTPS) and may not be supported on all platforms/browsers.  
+ *
+ * @param opts Set `{ type: "share" }` to share the screenshot. Additional options like `filename`, `title`, `text`, and `url` can be provided.
+ * @returns A Promise that resolves with an object containing the blob and whether it was successfully shared.
+ * @category Utilities
+ *
+ * @example Share screenshot on mobile
+ * ```ts
+ * const result = await screenshot2({
+ *   type: "share",
+ *   filename: "my-creation.png",
+ *   title: "Check out my 3D scene!",
+ *   text: "I created this with Needle Engine",
+ *   url: "https://engine.needle.tools",
+ *   mimeType: "image/png",
+ * });
+ *
+ * if (result.shared) {
+ *   console.log("Screenshot shared successfully!");
+ * } else {
+ *   console.log("User cancelled or sharing not supported");
+ * }
+ * ```
+ *
+ * @example Share with fallback
+ * ```ts
+ * const result = await screenshot2({
+ *   type: "share",
+ *   filename: "screenshot.webp",
+ *   file_type: "image/webp",
+ * });
+ *
+ * if (!result.shared && result.blob) {
+ *   // Fallback: download the image instead
+ *   const url = URL.createObjectURL(result.blob);
+ *   saveImage(url, "screenshot.webp");
+ *   URL.revokeObjectURL(url);
+ * }
+ * ```
+ */
 export function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOptionsShareReturnType>;
+
+/**
+ * Take a screenshot from the current scene with advanced options.  
+ *
+ * This is the main screenshot function in Needle Engine with support for multiple output formats:  
+ * - **Data URL** (default): Returns a base64-encoded string suitable for img src attributes
+ * - **Texture**: Returns a Three.js Texture that can be applied to materials
+ * - **Blob**: Returns a Blob for uploading or processing (async)
+ * - **Share**: Uses the Web Share API to share the screenshot (async, mobile-friendly)
+ *
+ * @param opts Screenshot options. Use the `type` property to specify output format. See {@link ScreenshotOptions} for all available options.
+ * @returns Depending on the `type` option:
+ * - Data URL (string) when `type` is undefined or not specified
+ * - Texture when `type: "texture"`
+ * - Promise<Blob | null> when `type: "blob"`
+ * - Promise<{blob, shared}> when `type: "share"`
+ *
+ * Returns null (or Promise resolving to null) if the screenshot could not be taken.
+ *
+ * @category Utilities
+ *
+ * @example WebXR / AR Screenshots
+ * ```ts
+ * // Screenshots work automatically in WebXR sessions
+ * // The camera feed will be composited with your 3D content
+ * const dataUrl = screenshot2({
+ *   width: 1920,
+ *   height: 1080
+ * });
+ * ```
+ *
+ * **Note for AR Screenshots**: To include the device camera feed in AR screenshots, you need to request camera access.
+ * This is done automatically when you use {@link WebARCameraBackground} component in your scene.
+ * If you're not using WebARCameraBackground, you can request camera access manually:
+ * ```ts
+ * export class MyComponent extends Behaviour {
+ *   onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void {
+ *     if (mode === "immersive-ar") {
+ *       args.optionalFeatures = args.optionalFeatures || [];
+ *       args.optionalFeatures.push('camera-access');
+ *     }
+ *   }
+ * }
+ * ```
+ * Without camera access, AR screenshots will only show your 3D content without the real-world background.
+ *
+ * @example Combining multiple options
+ * ```ts
+ * // High-res transparent screenshot with custom camera
+ * const myCamera = this.gameObject.getComponent(Camera);
+ * const texture = screenshot2({
+ *   type: "texture",
+ *   camera: myCamera,
+ *   width: 2048,
+ *   height: 2048,
+ *   transparent: true,
+ *   trim: true,
+ *   render_events: true, // Ensure reflection probes are updated
+ * });
+ * ```
+ *
+ * @see {@link screenshot} for a simpler alternative with fewer options
+ * @see {@link saveImage} for downloading data URLs
+ * @see {@link ScreenshotOptions} for all available options
+ */
 export function screenshot2(opts: ScreenshotOptionsDataUrl | ScreenshotOptionsTexture | ScreenshotOptionsBlob | ScreenshotOptionsShare)
     : Texture | string | null | Promise<Blob | null> | Promise<ScreenshotOptionsShareReturnType> {
 

package/src/engine/engine_utils_screenshot.xr.ts

@@ -5,7 +5,7 @@ import { isDevEnvironment, showBalloonError } from "./debug/index.js";
 // Adapted from WebARCameraBackground
 
 /**
- * Assigns the camera feed to a texture - this must be called during the render loop
+ * Assigns the camera feed to a texture - this must be called during the render loop.  
  */
 export function updateTextureFromXRFrame(renderer: WebGLRenderer, target: Texture): boolean {
 

package/src/engine/extensions/NEEDLE_materialx.ts

@@ -1,8 +1,9 @@
 import { Loader, LoadingManager, Material, Object3D, TextureLoader } from "three";
-import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader";
-import { ObjectUtils } from "../engine_create_objects";
-import { MODULES } from "../engine_modules";
-import { IContext } from "../engine_types";
+import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+import { ObjectUtils } from "../engine_create_objects.js";
+import { MODULES } from "../engine_modules.js";
+import { IContext } from "../engine_types.js";
 
 
 // #region Utils

package/src/engine/extensions/NEEDLE_techniques_webgl.ts

@@ -621,6 +621,9 @@ function createUniformProperties(material: CustomShader) {
                 case "_Color":
                     defineProperty("color", key);
                     break;
+                case "_map":
+                    defineProperty("map", key);
+                    break;
                 // case "_Metallic":
                 //     defineProperty("metalness", key);
                 //     break;

package/src/engine/extensions/index.ts

@@ -2,6 +2,6 @@ export { compareAssociation } from "./extension_utils.js"
 export * from "./extensions.js"
 export * from "./NEEDLE_animator_controller_model.js"
 export { SceneLightSettings } from "./NEEDLE_lighting_settings.js"
+export { MaterialX } from "./NEEDLE_materialx.js"
 export * from "./NEEDLE_progressive.js"
-export { CustomShader } from "./NEEDLE_techniques_webgl.js"
-export { MaterialX } from "./NEEDLE_materialx.js"
+export { CustomShader } from "./NEEDLE_techniques_webgl.js"

package/src/engine/xr/NeedleXRSession.ts

@@ -279,7 +279,12 @@ const $initialFov = Symbol("initial-fov");
  * The XRRig can be accessed via the `rig` property  
  * Set a custom XRRig via `NeedleXRSession.addRig(...)` or `NeedleXRSession.removeRig(...)`  
  * By default the active XRRig with the highest priority in the scene is used
+ *
+ * ### Screenshots in XR
+ * Screenshots work automatically during XR sessions, including AR camera feed compositing. See {@link screenshot2} for more information.
+ *
  * @category XR
+ * @see {@link screenshot2} for taking screenshots in XR sessions
  */
 export class NeedleXRSession implements INeedleXRSession {
 

package/src/engine-components/AlignmentConstraint.ts

@@ -5,12 +5,32 @@ import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * Aligns this GameObject between two other GameObjects, scaling it to fit the distance.  
- * You can use this to create dynamic beams or connectors between objects.
+ * The [AlignmentConstraint](https://engine.needle.tools/docs/api/AlignmentConstraint) positions and scales this GameObject to span between two target objects.
+ * The object is rotated to face `to` and scaled along Z to match the distance.  
  *
- * @summary Aligns and scales the object between two target GameObjects
+ * **Use cases:**  
+ * - Dynamic beams or laser effects between objects  
+ * - Stretchy connectors or ropes  
+ * - Visual links between UI elements
+ * - Debug lines between transforms
+ *
+ * **How it works:**  
+ * - Position: Centered between `from` and `to` (or at `from` if not centered)
+ * - Rotation: Looks at `to` from `from`
+ * - Scale: Z-axis scales to match distance, X/Y use `width`
+ *
+ * @example Create a beam between two objects
+ * ```ts
+ * const beam = beamMesh.addComponent(AlignmentConstraint);
+ * // Set targets via serialized properties in editor
+ * // or via code if properties are exposed
+ * ```
+ *
+ * @summary Aligns and scales object between two targets
  * @category Constraints
- * @group Components 
+ * @group Components
+ * @see {@link LookAtConstraint} for rotation-only constraints
+ * @see {@link SmoothFollow} for following with smoothing
  **/
 export class AlignmentConstraint extends Behaviour {
 

package/src/engine-components/Animation.ts

@@ -10,6 +10,12 @@ import { Behaviour } from "./Component.js";
 
 const debug = getParam("debuganimation");
 
+/**
+ * Options for controlling animation playback via {@link Animation.play}.  
+ * All options are optional - defaults are sensible for most use cases.
+ *
+ * @see {@link Animation} for the component that uses these options
+ */
 export declare type PlayOptions = {
     /**
      * The fade duration in seconds for the action to fade in and other actions to fade out (if exclusive is enabled)
@@ -59,11 +65,47 @@ declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 class Vec2 { x!: number; y!: number }
 
 /**
- * Animation component to play animations on a GameObject.
+ * Animation component to play animations on a GameObject.  
+ * For simpler animation needs compared to {@link Animator}, this component directly  
+ * plays AnimationClips without state machine logic.  
+ *
+ * **Key features:**
+ * - Play animations by index, name, or clip reference
+ * - Cross-fade between animations with `fadeDuration`
+ * - Loop or play once with optional clamping
+ * - Random start time and speed variation
+ * - Promise-based completion handling
+ * 
  * 
- * @summary Plays animations from AnimationClips 
+ * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)  
+ *
+ * @example Play animation by name
+ * ```ts
+ * const anim = this.gameObject.getComponent(Animation);
+ * await anim?.play("Walk", { loop: true, fadeDuration: 0.3 });
+ * ```
+ *
+ * @example Play with options
+ * ```ts
+ * anim?.play(0, {
+ *   loop: false,
+ *   clampWhenFinished: true,
+ *   speed: 2
+ * });
+ * ```
+ *
+ * @summary Plays animations from AnimationClips
  * @category Animation and Sequencing
  * @group Components
+ * @see {@link Animator} for state machine-based animation
+ * @see {@link PlayOptions} for all playback options  
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
+ * @link https://engine.needle.tools/samples/imunogard/
+ * 
+ * @link https://engine.needle.tools/docs/blender/animation.html
+ * 
+ * ![](https://cloud.needle.tools/-/media/vAYv-kU-eMpICqQZHJktCA.gif)
+ * 
  */
 export class Animation extends Behaviour implements IAnimationComponent {
 

package/src/engine-components/Animator.ts

@@ -12,7 +12,7 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debuganimator");
 
 /** 
- * Represents an event emitted by an animation mixer
+ * Represents an event emitted by an animation mixer  
  * @category Animation and Sequencing
  * @group Components
  */
@@ -28,7 +28,7 @@ export declare class MixerEvent {
 }
 
 /**
- * Configuration options for playing animations
+ * Configuration options for playing animations  
  * @category Animation and Sequencing
  */
 export declare class PlayOptions {
@@ -38,15 +38,48 @@ export declare class PlayOptions {
     clampWhenFinished?: boolean;
 }
 
-/** 
- * The Animator component plays and manages animations on a GameObject. 
- * It works with an {@link AnimatorController} to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
+/**
+ * Animator plays and manages state-machine based animations on a GameObject.  
+ * Uses an {@link AnimatorController} for state transitions, blending, and parameters.  
+ *
+ * **State machine animations:**  
+ * Define animation states and transitions in Unity's Animator window or in [Blender's Animator Controller editor](https://engine.needle.tools/docs/blender/animation.html)
+ * Control transitions via parameters (bool, int, float, trigger).  
  * 
+ * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)  
+ *
+ * **Creating at runtime:**  
+ * Use `AnimatorController.createFromClips()` to create controllers from code.  
+ *
+ * **Parameters:**  
+ * - `setTrigger(name)` - Trigger a one-shot transition
+ * - `setBool(name, value)` - Set boolean parameter
+ * - `setFloat(name, value)` - Set float parameter
+ * - `setInteger(name, value)` - Set integer parameter
+ *
+ * @example Trigger animation state
+ * ```ts
+ * const animator = myCharacter.getComponent(Animator);
+ * animator.setTrigger("Jump");
+ * animator.setFloat("Speed", 5);
+ * animator.setBool("IsRunning", true);
+ * ```
+ *
+ * @example Listen to animation events
+ * ```ts
+ * animator.onLoop(evt => console.log("Animation looped"));
+ * animator.onFinished(evt => console.log("Animation finished"));
+ * ```
+ *
  * @summary Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
-*/
+ * @see {@link AnimatorController} for state machine configuration
+ * @see {@link Animation} for simple clip playback
+ * @see {@link PlayableDirector} for timeline-based animation
+ * 
+ * @link https://engine.needle.tools/docs/blender/animation.html
+ */
 export class Animator extends Behaviour implements IAnimationComponent {
 
     /** 

package/src/engine-components/AudioListener.ts

@@ -5,7 +5,7 @@ import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 /**
- * AudioListener represents a listener that can hear audio sources in the scene.
+ * The [AudioListener](https://engine.needle.tools/docs/api/AudioListener) represents a listener that can hear audio sources in the scene.
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
  * 

package/src/engine-components/AudioSource.ts

@@ -37,24 +37,46 @@ export enum AudioRolloffMode {
 }
 
 
-/** 
- * Plays audio clips in the scene, with support for spatial positioning.
- * 
- * The AudioSource component can play audio files or media streams with
- * options for spatial blending, volume control, looping, and more.
- * 
- * When a page loses visibility (tab becomes inactive), audio will automatically
- * pause unless {@link playInBackground} is set to true. On mobile devices, audio always
- * pauses regardless of this setting. When the page becomes visible again,
- * previously playing audio will resume.
- * 
- * AudioSource also responds to application mute state changes. When the application
- * is muted, the volume is set to 0. When unmuted, the volume
- * returns to its previous value.
- * 
+/**
+ * Plays audio clips in the scene with support for spatial (3D) positioning.  
+ *
+ * **Browser autoplay policies:**  
+ * Web browsers require user interaction before playing audio. Use  
+ * `AudioSource.userInteractionRegistered` to check if playback is allowed,  
+ * or `registerWaitForAllowAudio()` to queue playback until interaction occurs.  
+ *
+ * **Spatial audio:**  
+ * Set `spatialBlend` to 1 for full 3D positioning, or 0 for 2D (non-spatial).  
+ * Requires an {@link AudioListener} in the scene (typically on the camera).  
+ *
+ * **Visibility handling:**  
+ * Audio automatically pauses when the tab is hidden unless `playInBackground = true`.  
+ * On mobile, audio always pauses in background regardless of this setting.  
+ *
+ * @example Play audio on button click
+ * ```ts
+ * onClick() {
+ *   const audio = this.getComponent(AudioSource);
+ *   audio.play();
+ * }
+ * ```
+ *
+ * @example Wait for user interaction
+ * ```ts
+ * AudioSource.registerWaitForAllowAudio(() => {
+ *   this.getComponent(AudioSource)?.play();
+ * });
+ * ```
+ *
  * @summary Plays audio clips from files or media streams
  * @category Multimedia
  * @group Components
+ * @see {@link AudioListener} for the audio receiver component
+ * @see {@link AudioRolloffMode} for distance attenuation options
+ * @see {@link Voip} for voice communication
+ * @see {@link PlayableDirector} for timeline-based audio  
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=audio
+ * @link https://spatial-audio-zubckswmztj.needle.run/
  */
 export class AudioSource extends Behaviour {