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

package/src/engine-components/timeline/PlayableDirector.ts

@@ -17,20 +17,15 @@ import * as Tracks from "./TimelineTracks.js";
 const debug = getParam("debugtimeline");
 
 /**
- * The wrap mode of the {@link PlayableDirector}.
+ * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
+ * @see {@link PlayableDirector.extrapolationMode}
  */
 export enum DirectorWrapMode {
-    /// <summary>
-    ///   <para>Hold the last frame when the playable time reaches it's duration.</para>
-    /// </summary>
+    /** Hold the last frame when playback reaches the end of the timeline. */
     Hold = 0,
-    /// <summary>
-    ///   <para>Loop back to zero time and continue playing.</para>
-    /// </summary>
+    /** Loop back to the start and continue playing indefinitely. */
     Loop = 1,
-    /// <summary>
-    ///   <para>Do not keep playing when the time reaches the duration.</para>
-    /// </summary>
+    /** Stop playback when the end is reached. The timeline will not loop. */
     None = 2,
 }
 
@@ -53,26 +48,76 @@ export enum ClipExtrapolation {
 export type CreateTrackFunction = (director: PlayableDirector, track: Models.TrackModel) => Tracks.TrackHandler | undefined | null;
 
 /**
- * The PlayableDirector component is the main component to control timelines in needle engine.
- * It is used to play, pause, stop and evaluate timelines.  
- * Assign a TimelineAsset to the `playableAsset` property to start playing a timeline.
+ * PlayableDirector is the main component for controlling timelines in Needle Engine.  
+ * It orchestrates playback of TimelineAssets containing animation, audio, signal,  
+ * control, and activation tracks.  
+ *
+ * **Supported track types:**  
+ * - Animation tracks - animate objects using AnimationClips
+ * - Audio tracks - play synchronized audio
+ * - Activation tracks - show/hide objects at specific times
+ * - Signal tracks - trigger events at specific points
+ * - Control tracks - control nested timelines or prefab instances
+ * - Marker tracks - add metadata and navigation points  
+ * 
+ * [![](https://cloud.needle.tools/-/media/HFudFwl8J8D-Kt_VPu7pRw.gif)](https://engine.needle.tools/samples/bike-scrollytelling-responsive-3d)
+ * 
+ * [![](https://cloud.needle.tools/-/media/xJ1rI3STbZRnOoWJrSzqlQ.gif)](https://app.songsofcultures.com/?scene=little-brother)
+ *
+ * **Playback control:**    
+ * Use `play()`, `pause()`, `stop()` for basic control.  
+ * Set `time` directly and call `evaluate()` for scrubbing.  
+ * Adjust `speed` for playback rate and `weight` for blending.  
+ *
+ * @example Basic timeline playback
+ * ```ts
+ * const director = myObject.getComponent(PlayableDirector);
+ * director.play();
+ * // Jump to specific time
+ * director.time = 2.5;
+ * director.evaluate();
+ * ```
+ *
+ * @example Control playback speed
+ * ```ts
+ * director.speed = 0.5; // Half speed
+ * director.speed = -1;  // Reverse playback
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples-uploads/product-flyover/
+ *
  * @summary Controls and plays TimelineAssets
  * @category Animation and Sequencing
  * @group Components
+ * @see {@link Animator} for playing individual AnimationClips
+ * @see {@link AudioSource} for standalone audio playback
+ * @see {@link SignalReceiver} for handling timeline signals
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
+ * @link https://app.songsofcultures.com/  
  */
 export class PlayableDirector extends Behaviour {
 
     private static createTrackFunctions: { [key: string]: CreateTrackFunction } = {};
+
+    /**
+     * Register a function to create a track handler for a custom track type.
+     * This allows you to extend the timeline system with your own track types and handlers.
+     */
     static registerCreateTrack(type: string, fn: CreateTrackFunction) {
         this.createTrackFunctions[type] = fn;
     }
 
     /**
-     * The timeline asset that is played by this director.
+     * The timeline asset containing tracks, clips, and markers that this director will play.
+     * Assign a timeline asset exported from Unity or Blender to enable playback.
      */
     playableAsset?: Models.TimelineAssetModel;
 
-    /** Set to true to start playing the timeline when the scene starts */
+    /**
+     * When true, the timeline starts playing automatically when the component awakens.
+     * Set to false to control playback manually via `play()`.
+     * @default false
+     */
     @serializable()
     playOnAwake?: boolean;
 
@@ -83,11 +128,18 @@ export class PlayableDirector extends Behaviour {
     @serializable()
     extrapolationMode: DirectorWrapMode = DirectorWrapMode.Loop;
 
-    /** @returns true if the timeline is currently playing */
+    /** Returns true if the timeline is currently playing (not paused or stopped). */
     get isPlaying(): boolean { return this._isPlaying; }
-    /** @returns true if the timeline is currently paused */
+    /** Returns true if the timeline is currently paused. */
     get isPaused(): boolean { return this._isPaused; }
-    /** the current time of the timeline */
+    /**
+     * The current playback time in seconds. Set this and call `evaluate()` to scrub.
+     * @example Scrub to a specific time
+     * ```ts
+     * director.time = 5.0;
+     * director.evaluate();
+     * ```
+     */
     get time(): number { return this._time; }
     set time(value: number) {
         if (typeof value === "number" && !Number.isNaN(value))
@@ -96,17 +148,32 @@ export class PlayableDirector extends Behaviour {
             console.error("INVALID TIMELINE.TIME VALUE", value, this.name)
         };
     }
-    /** the duration of the timeline */
+    /** The total duration of the timeline in seconds (read from the longest track/clip). */
     get duration(): number { return this._duration; }
     set duration(value: number) { this._duration = value; }
-    /** the weight of the timeline. Set to a value below 1 to blend with other timelines */
+    /**
+     * The blend weight of the timeline (0-1). Use values below 1 to blend
+     * timeline animations with other animations like those from an Animator.
+     */
     get weight(): number { return this._weight; };
     set weight(value: number) { this._weight = value; }
-    /** the playback speed of the timeline */
+    /**
+     * The playback speed multiplier. Set to negative values for reverse playback.
+     * @example Reverse playback at double speed
+     * ```ts
+     * director.speed = -2;
+     * ```
+     */
     get speed(): number { return this._speed; }
     set speed(value: number) { this._speed = value; }
 
-    /** When enabled the timeline will wait for audio tracks to load at the current time before starting to play */
+    /**
+     * When true, `play()` will wait for audio tracks to load and for user interaction  
+     * before starting playback. Web browsers require user interaction (click/tap) before  
+     * allowing audio to play - this ensures audio is synchronized with the timeline.  
+     * Set to false if you need immediate visual playback and can tolerate audio delay.  
+     * @default true
+     */
     waitForAudio: boolean = true;
 
     private _visibilityChangeEvt?: any;
@@ -223,9 +290,9 @@ export class PlayableDirector extends Behaviour {
                 await delay(200);
         }
         this.invokeStateChangedMethodsOnTracks();
-        // Update timeline in LateUpdate to give other scripts time to react to the updated state
-        // e.g. if we animate OrbitControls look at target we want those changes to be applied in onBeforeRender
-        // if we use onBeforeRender here it will be called *after* the regular onBeforeRender events
+        // Update timeline in LateUpdate to give other scripts time to react to the updated state  
+        // e.g. if we animate OrbitControls look at target we want those changes to be applied in onBeforeRender  
+        // if we use onBeforeRender here it will be called *after* the regular onBeforeRender events  
         // which is too late
         this._internalUpdateRoutine = this.startCoroutine(this.internalUpdate(), FrameEvent.LateUpdate);
     }
@@ -762,8 +829,18 @@ export class PlayableDirector extends Behaviour {
     }
 }
 
-/** 
- * Experimental interface for receiving timeline animation callbacks. Register at the PlayableDirector
+/**
+ * Interface for receiving callbacks during timeline animation evaluation.  
+ * Allows modification of position/rotation values before they are applied.  
+ *
+ * **Registration:**
+ * ```ts
+ * director.registerAnimationCallback(this);
+ * // Later: director.unregisterAnimationCallback(this);
+ * ```
+ *
+ * @experimental This interface may change in future versions
+ * @see {@link PlayableDirector.registerAnimationCallback}
  */
 export interface ITimelineAnimationCallbacks {
     /**

package/src/engine-components/ui/Button.ts

@@ -61,12 +61,38 @@ class AnimationTriggers {
 }
 
 /**
- * Button is a UI component that can be clicked by the user to perform an action.  
- * It supports different visual states such as normal, highlighted, pressed, and disabled.  
- * You can customize the button's appearance using colors or animations for each state.
+ * Button is a UI component that can be clicked to trigger actions.  
+ * Supports visual states (normal, highlighted, pressed, disabled) with  
+ * color tints or animation transitions.  
+ *
+ * **Visual transitions:**  
+ * - `ColorTint` - Tint the button image with state colors
+ * - `Animation` - Trigger animator states for each button state
+ * - `SpriteSwap` - Swap sprites for each state (not fully supported)
+ *
+ * **Requirements:**  
+ * - Typically paired with an {@link Image} component for visuals or any 3D object
+ *
+ * @example Listen to button clicks
+ * ```ts
+ * const button = myButton.getComponent(Button);
+ * button.onClick.addEventListener(() => {
+ *   console.log("Button clicked!");
+ * });
+ * ```
+ *
+ * @example Programmatically click a button
+ * ```ts
+ * button.click(); // Triggers onClick event
+ * ```
+ *
  * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
+ * @see {@link EventList} for onClick callback handling
+ * @see {@link Image} for button visuals
+ * @see {@link GraphicRaycaster} for UI interaction
+ * @see {@link Transition} for visual state options
  */
 export class Button extends Behaviour implements IPointerEventHandler {
 

package/src/engine-components/ui/Canvas.ts

@@ -26,12 +26,37 @@ const debugLayout = getParam("debuguilayout");
 
 /**
  * Canvas is the root component for all UI elements in a scene.  
- * It defines the area where UI elements are rendered and manages their layout and rendering settings.  
- * Canvases can be set to render in world space or screen space (overlay or camera).  
- * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
+ * Defines the rendering area and manages layout for child UI elements.  
+ *
+ * **Render modes:**  
+ * - `WorldSpace` - UI exists in 3D space, can be viewed from any angle  
+ * - `ScreenSpaceOverlay` - UI rendered on top of everything (HUD)  
+ * - `ScreenSpaceCamera` - UI rendered at a distance from a specific camera  
+ *
+ * **Usage:**  
+ * All UI components ({@link Button}, {@link Text}, {@link Image}) must be
+ * children of a Canvas to render correctly. Multiple canvases can exist
+ * in a scene with different settings.
+ *
+ * **Rendering options:**  
+ * - `renderOnTop` - Always render above other objects
+ * - `depthWrite` - Write to depth buffer (affects occlusion)
+ * - `doubleSided` - Render both sides of UI elements
+ *
+ * @example Create a world-space UI panel
+ * ```ts
+ * const canvas = panel.getComponent(Canvas);
+ * canvas.renderMode = RenderMode.WorldSpace;
+ * canvas.doubleSided = true;
+ * ```
+ *
  * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
+ * @see {@link RenderMode} for rendering options
+ * @see {@link RectTransform} for UI layout
+ * @see {@link Button} for clickable UI elements
+ * @see {@link Text} for UI text rendering
  */
 export class Canvas extends UIRootComponent implements ICanvas {
 

package/src/engine-components/ui/Image.ts

@@ -12,12 +12,31 @@ class Sprite {
 }
 
 /**
- * Image is a UI component that displays a sprite (2D image) in the user interface.  
- * You can set the image property to assign a texture to be displayed.  
- * The sprite can be customized with various properties such as color tinting and pixel density.
+ * Image displays a sprite (2D texture) in the UI. Can be used for icons,  
+ * backgrounds, or any visual element that needs a texture.  
+ *
+ * **Properties:**  
+ * - `image` - Direct texture assignment (convenience property)
+ * - `sprite` - Sprite object containing texture and rect info
+ * - `color` - Tint color applied to the image (inherited from Graphic)
+ *
+ * **Usage with Button:**  
+ * Image is commonly paired with {@link Button} to create clickable  
+ * UI elements with visual feedback via color tinting.  
+ *
+ * @example Set an image texture
+ * ```ts
+ * const img = myIcon.getComponent(Image);
+ * img.image = myTexture;
+ * img.color = new RGBAColor(1, 0.5, 0.5, 1); // Red tint
+ * ```
+ *
  * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for the UI root
+ * @see {@link Button} for clickable images
+ * @see {@link RawImage} for non-UI image display
  */
 export class Image extends MaskableGraphic {
 

package/src/engine-components/ui/Raycaster.ts

@@ -7,9 +7,21 @@ import { Behaviour } from "../Component.js";
 import { EventSystem } from "./EventSystem.js";
 
 
-/** Derive from this class to create your own custom Raycaster  
- * If you override awake, onEnable or onDisable, be sure to call the base class methods  
- * Implement `performRaycast` to perform your custom raycasting logic
+/**
+ * Base class for raycasters that detect pointer interactions.  
+ * Derive from this class to create custom raycasting logic. 
+ *
+ * **Built-in raycasters:**  
+ * - {@link ObjectRaycaster} - Raycasts against 3D objects
+ * - {@link GraphicRaycaster} - Raycasts against UI elements
+ * - {@link SpatialGrabRaycaster} - Sphere overlap for XR grab
+ *
+ * **Important:** If you override `awake`, `onEnable`, or `onDisable`,  
+ * call the base class methods to ensure proper registration with {@link EventSystem}.
+ *
+ * @category Interactivity
+ * @group Components
+ * @see {@link EventSystem} for the event dispatch system
  */
 export abstract class Raycaster extends Behaviour {
     awake(): void {
@@ -29,10 +41,22 @@ export abstract class Raycaster extends Behaviour {
 
 
 /**
- * A Raycaster that performs raycasting against its own GameObject.  
+ * ObjectRaycaster enables pointer interactions with 3D objects.  
+ * Add this component to any object that needs click/hover detection.  
+ *
+ * **Usage:**  
+ * Objects with ObjectRaycaster will receive pointer events when  
+ * they implement interfaces like {@link IPointerClickHandler}.
  * 
+ * **Note:**  
+ * In older Needle Engine versions the ObjectRaycaster was required to be added to the Scene.  
+ * This is no longer the case - the EventSystem will automatically handle raycasts.  
+ *
+ *
  * @category Interactivity
  * @group Components
+ * @see {@link IPointerClickHandler} for click events
+ * @see {@link DragControls} for drag interactions
  */
 export class ObjectRaycaster extends Raycaster {
     private targets: Object3D[] | null = null;
@@ -73,11 +97,27 @@ export class ObjectRaycaster extends Raycaster {
 
 
 /**
- * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
- * 
+ * GraphicRaycaster enables pointer interactions with UI elements.
+ * Add this to a {@link Canvas} or UI hierarchy to enable button clicks,
+ * hover effects, and other UI interactions.
+ *
+ * **Requirements:**
+ * - Must be on the same object as a Canvas or on a parent
+ * - UI elements need proper RectTransform setup
+ *
+ * @example Enable UI interaction
+ * ```ts
+ * // Add to Canvas object
+ * canvas.addComponent(GraphicRaycaster);
+ * // Now buttons and other UI elements will respond to clicks
+ * ```
+ *
  * @summary Raycaster for UI elements
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for UI root
+ * @see {@link Button} for clickable UI
+ * @see {@link EventSystem} for event handling
  */
 export class GraphicRaycaster extends ObjectRaycaster {
     // eventCamera: Camera | null = null;
@@ -91,10 +131,19 @@ export class GraphicRaycaster extends ObjectRaycaster {
 }
 
 /**
- * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.  
- * 
+ * SpatialGrabRaycaster enables direct grab interactions in VR/AR.
+ * Uses sphere overlap detection around the controller/hand position
+ * to allow grabbing objects by reaching into them.
+ *
+ * **Features:**
+ * - Active only during XR sessions
+ * - Can be globally disabled via `SpatialGrabRaycaster.allow`
+ * - Works alongside ray-based interaction
+ *
  * @category XR
  * @group Components
+ * @see {@link WebXR} for XR session management
+ * @see {@link DragControls} for object manipulation
  */
 export class SpatialGrabRaycaster extends Raycaster {
 

package/src/engine-components/ui/Text.ts

@@ -40,11 +40,33 @@ export enum FontStyle {
 }
 
 /**
- * Text is a UI component that displays text in the user interface.
- * 
+ * Text displays text content in the UI. Supports custom fonts, colors,
+ * alignment, and basic rich text formatting.
+ *
+ * **Text properties:**
+ * - `text` - The string content to display
+ * - `fontSize` - Size of the text in pixels
+ * - `color` - Text color (inherited from Graphic)
+ * - `alignment` - Text anchor position (UpperLeft, MiddleCenter, etc.)
+ *
+ * **Fonts:**
+ * Set the `font` property to a URL pointing to a font file.
+ * Supports MSDF (Multi-channel Signed Distance Field) fonts for crisp rendering.
+ *
+ * @example Update text at runtime
+ * ```ts
+ * const text = myLabel.getComponent(Text);
+ * text.text = "Score: " + score;
+ * text.fontSize = 24;
+ * text.color = new RGBAColor(1, 1, 1, 1);
+ * ```
+ *
  * @summary Display text in the UI
  * @category User Interface
  * @group Components
+ * @see {@link Canvas} for the UI root
+ * @see {@link TextAnchor} for alignment options
+ * @see {@link FontStyle} for bold/italic styles
  */
 export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiver {
 

package/src/engine-components/webxr/TeleportTarget.ts

@@ -1,12 +1,31 @@
 import { Behaviour } from "../Component.js";
 import type { XRControllerMovement } from "./controllers/XRControllerMovement.js";
 
-/** 
- * This component is just used as a marker on objects for WebXR teleportation  
- * The {@link XRControllerMovement} component can be configured to check if the TeleportTarget component is present on an object to allow teleporting to that object.
- * 
+/**
+ * Marks a GameObject as a valid teleportation target for VR locomotion.  
+ * Add this component to objects or surfaces where users should be able to teleport.  
+ *
+ * **Usage:**  
+ * - Add to floor surfaces, platforms, or designated teleport spots
+ * - Works with {@link XRControllerMovement} component's teleport system
+ * - Can be used to restrict teleportation to specific areas
+ *
+ * **Setup:**
+ * 1. Add this component to GameObjects that should be teleport destinations
+ * 2. Configure {@link XRControllerMovement} to use teleport targets (optional)
+ * 3. Test teleportation in VR mode
+ *
+ * @example
+ * ```ts
+ * // Make a platform teleportable
+ * const platform = myPlatform.addComponent(TeleportTarget);
+ * ```
+ *
+ * @summary Marker component for valid VR teleportation destinations
  * @category XR
  * @group Components
+ * @see {@link XRControllerMovement} for VR locomotion and teleport configuration
+ * @see {@link WebXR} for general WebXR setup
  */
 export class TeleportTarget extends Behaviour {
 

package/src/engine-components/webxr/WebXR.ts

@@ -23,12 +23,13 @@ const debug = getParam("debugwebxr");
 const debugQuicklook = getParam("debugusdz");
 
 /**
- * Use the WebXR component to enable VR and AR on iOS and Android in your scene. VisionOS support is also provided via QuickLook USDZ export.  
+ * Use the WebXR component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.  
  * 
- * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
+ * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.  
  * 
- * - Example: https://samples.needle.tools/collaborative-sandbox
+ * ![](https://cloud.needle.tools/-/media/gcj_YoSns8FivafQRiCiOQ.gif)
  * 
+ *
  * @example Enable VR and AR support using code
  * ```ts
  * import { onStart, WebXR } from "@needle-tools/engine";
@@ -54,6 +55,13 @@ const debugQuicklook = getParam("debugusdz");
  * @summary WebXR Component for VR and AR support
  * @category XR
  * @group Components
+ * @see {@link NeedleXRSession} for low-level XR API
+ * @see {@link XRControllerMovement} for VR locomotion
+ * @see {@link WebARSessionRoot} for AR session configuration
+ * @see {@link Avatar} for networked user avatars
+ * @link https://engine.needle.tools/docs/xr.html
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
+ * @link https://engine.needle.tools/samples/collaborative-sandbox
  */
 export class WebXR extends Behaviour {
 

package/src/engine-components/webxr/WebXRAvatar.ts

@@ -6,32 +6,61 @@ import { XRFlag } from "./XRFlag.js";
 
 export const debug = getParam("debugavatar");
 
+/**
+ * Event arguments for avatar marker creation and destruction events
+ */
 export type AvatarMarkerEventArgs = {
+    /** The AvatarMarker component instance */
     avatarMarker: AvatarMarker;
+    /** The GameObject that contains the avatar marker */
     gameObject: Object3D;
 }
 
-/** 
- * This is used to mark an object being controlled / owned by a player   
- * This system might be refactored and moved to a more centralized place in a future version
+/**
+ * Marks a GameObject as being controlled or owned by a player in networked XR sessions.  
+ * This is used internally by the networking system to identify player-controlled objects.  
+ *
+ * **Note:** This is an internal marker class. For most use cases, use the {@link Avatar} component instead.  
+ *
+ * @summary Internal marker for player-controlled objects in networked sessions
+ * @category XR
+ * @category Networking
+ * @group Components
+ * @see {@link Avatar} for avatar setup and configuration
  */
-// We might be updating this system in the future to a centralized API (PlayerView)  
+// We might be updating this system in the future to a centralized API (PlayerView)
 // but since currently quite a few core components rely on it, we're keeping it for now
 export class AvatarMarker extends Behaviour {
 
+    /**
+     * Get an avatar marker by index from the global list of avatar markers.
+     * @param index The index in the instances array
+     * @returns The AvatarMarker at the specified index, or null if index is out of bounds
+     */
     public static getAvatar(index: number): AvatarMarker | null {
         if (index >= 0 && index < AvatarMarker.instances.length)
             return AvatarMarker.instances[index];
         return null;
     }
 
+    /** Global list of all active AvatarMarker instances */
     public static instances: AvatarMarker[] = [];
 
+    /**
+     * Subscribe to avatar marker creation events.
+     * @param cb Callback function called when a new avatar marker is created
+     * @returns The callback function (for removal)
+     */
     public static onAvatarMarkerCreated(cb: (args: AvatarMarkerEventArgs) => void): Function {
         AvatarMarker._onNewAvatarMarkerAdded.push(cb);
         return cb;
     }
 
+    /**
+     * Subscribe to avatar marker destruction events.
+     * @param cb Callback function called when an avatar marker is destroyed
+     * @returns The callback function (for removal)
+     */
     public static onAvatarMarkerDestroyed(cb: (args: AvatarMarkerEventArgs) => void): Function {
         AvatarMarker._onAvatarMarkerDestroyed.push(cb);
         return cb;
@@ -41,9 +70,12 @@ export class AvatarMarker extends Behaviour {
     private static _onAvatarMarkerDestroyed: Array<(args: AvatarMarkerEventArgs) => void> = [];
 
 
+    /** The network connection ID of the player who owns this avatar */
     public connectionId!: string;
+    /** Reference to the avatar GameObject with optional XR flags */
     public avatar?: Object3D & { flags?: XRFlag[] }
 
+    /** @internal */
     awake() {
         AvatarMarker.instances.push(this);
         if (debug)
@@ -53,6 +85,7 @@ export class AvatarMarker extends Behaviour {
             cb({ avatarMarker: this, gameObject: this.gameObject });
     }
 
+    /** @internal */
     onDestroy() {
         AvatarMarker.instances.splice(AvatarMarker.instances.indexOf(this), 1);
 
@@ -60,6 +93,10 @@ export class AvatarMarker extends Behaviour {
             cb({ avatarMarker: this, gameObject: this.gameObject });
     }
 
+    /**
+     * Check if this avatar marker represents the local player.
+     * @returns True if this avatar belongs to the local player, false otherwise
+     */
     isLocalAvatar() {
         return this.connectionId === this.context.connection.connectionId;
     }