@needle-tools/engine 4.3.0-alpha → 4.3.0-alpha.1

package/dist/needle-engine.bundle.light.js

@@ -1760,15 +1760,15 @@ function AC() {
   return n || null;
 }
 const V0 = S("debugdefines");
-ko('if(!globalThis[""4.3.0-alpha""]) globalThis[""4.3.0-alpha""] = "0.0.0";');
+ko('if(!globalThis[""4.3.0-alpha.1""]) globalThis[""4.3.0-alpha.1""] = "0.0.0";');
 ko('if(!globalThis[""undefined""]) globalThis[""undefined""] = "unknown";');
-ko('if(!globalThis[""Fri Feb 28 2025 13:27:32 GMT+0100 (Central European Standard Time)""]) globalThis[""Fri Feb 28 2025 13:27:32 GMT+0100 (Central European Standard Time)""] = "unknown";');
+ko('if(!globalThis[""Mon Mar 03 2025 10:04:15 GMT+0100 (Central European Standard Time)""]) globalThis[""Mon Mar 03 2025 10:04:15 GMT+0100 (Central European Standard Time)""] = "unknown";');
 ko('if(!globalThis[""npk_74222a9fbd1b42572cdd3bf7f639eeb17a07d07f40a6185fac5f722e8fd34df9""]) globalThis[""npk_74222a9fbd1b42572cdd3bf7f639eeb17a07d07f40a6185fac5f722e8fd34df9""] = "unknown";');
-ko('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.3.0-alpha";');
+ko('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.3.0-alpha.1";');
 ko('globalThis["__NEEDLE_ENGINE_GENERATOR__"] = "undefined";');
-ko('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Fri Feb 28 2025 13:27:32 GMT+0100 (Central European Standard Time)";');
+ko('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Mon Mar 03 2025 10:04:15 GMT+0100 (Central European Standard Time)";');
 ko('globalThis["__NEEDLE_PUBLIC_KEY__"] = "npk_74222a9fbd1b42572cdd3bf7f639eeb17a07d07f40a6185fac5f722e8fd34df9";');
-const Ns = "4.3.0-alpha", bg = "undefined", H0 = "Fri Feb 28 2025 13:27:32 GMT+0100 (Central European Standard Time)";
+const Ns = "4.3.0-alpha.1", bg = "undefined", H0 = "Mon Mar 03 2025 10:04:15 GMT+0100 (Central European Standard Time)";
 V0 && console.log(`Engine version: ${Ns} (generator: ${bg})
 Project built at ${H0}`);
 const ud = "npk_74222a9fbd1b42572cdd3bf7f639eeb17a07d07f40a6185fac5f722e8fd34df9", yo = "needle_isActiveInHierarchy", fa = "builtin_components", fd = "needle_editor_guid";
@@ -11791,42 +11791,75 @@ function sb(n) {
 class C extends D {
   constructor() {
     super(...arguments);
+    /**
+     * Unique identifier for this GameObject
+     */
     r(this, "guid");
   }
+  /**
+   * Checks if a GameObject has been destroyed
+   * @param go The GameObject to check
+   * @returns True if the GameObject has been destroyed
+   */
   static isDestroyed(e) {
     return Qa(e);
   }
+  /**
+   * Sets the active state of a GameObject
+   * @param go The GameObject to modify
+   * @param active Whether the GameObject should be active
+   * @param processStart Whether to process the start callbacks if being activated
+   */
   static setActive(e, i, s = !0) {
     e && (bd(e, i), pd(e), i && s && cv(ee.Current, e));
   }
-  /** If the object is active (same as go.visible) */
+  /**
+   * Checks if the GameObject itself is active (same as go.visible)
+   * @param go The GameObject to check
+   * @returns True if the GameObject is active
+   */
   static isActiveSelf(e) {
     return Zc(e);
   }
-  /** If the object is active in the hierarchy (e.g. if any parent is invisible or not in the scene it will be false) 
-   * @param go object to check
-  */
+  /**
+   * Checks if the GameObject is active in the hierarchy (e.g. if any parent is invisible or not in the scene it will be false)
+   * @param go The GameObject to check
+   * @returns True if the GameObject is active in the hierarchy
+   */
   static isActiveInHierarchy(e) {
     return pO(e);
   }
+  /**
+   * Marks a GameObject to be rendered using instancing
+   * @param go The GameObject to mark
+   * @param instanced Whether the GameObject should use instanced rendering
+   */
   static markAsInstancedRendered(e, i) {
     mO(e, i);
   }
+  /**
+   * Checks if a GameObject is using instanced rendering
+   * @param instance The GameObject to check
+   * @returns True if the GameObject is using instanced rendering
+   */
   static isUsingInstancing(e) {
     return Ig(e);
   }
-  /** Run a callback for all components of the provided type on the provided object and its children (if recursive is true)
-   * @param instance object to run the method on
-   * @param cb callback to run on each component, "return undefined;" to continue and "return <anything>;" to break the loop
-   * @param recursive if true, the method will be run on all children as well
-   * @returns the last return value of the callback
+  /**
+   * Executes a callback for all components of the provided type on the provided object and its children
+   * @param instance Object to run the method on
+   * @param cb Callback to run on each component, "return undefined;" to continue and "return <anything>;" to break the loop
+   * @param recursive If true, the method will be run on all children as well
+   * @returns The last return value of the callback
    */
   static foreachComponent(e, i, s = !0) {
     return Ya(e, i, s);
   }
-  /** Creates a new instance of the provided object. The new instance will be created on all connected clients 
-   * @param instance object to instantiate
-   * @param opts options for the instantiation
+  /**
+   * Creates a new instance of the provided object that will be replicated to all connected clients
+   * @param instance Object to instantiate
+   * @param opts Options for the instantiation
+   * @returns The newly created instance or null if creation failed
    */
   static instantiateSynced(e, i) {
     return e ? fv(e, i) : null;
@@ -11834,24 +11867,31 @@ class C extends D {
   static instantiate(e, i = null) {
     return "isAssetReference" in e, Ka(e, i);
   }
-  /** Destroys a object on all connected clients (if you are in a networked session) 
-   * @param instance object to destroy
-  */
+  /**
+   * Destroys an object on all connected clients (if in a networked session)
+   * @param instance Object to destroy
+   * @param context Optional context to use
+   * @param recursive If true, all children will be destroyed as well
+   */
   static destroySynced(e, i, s = !0) {
     if (!e)
       return;
     const o = e;
     i = i ?? ee.Current, ju(o, i.connection, s);
   }
-  /** Destroys a object
-   * @param instance object to destroy
-   * @param recursive if true, all children will be destroyed as well. true by default
+  /**
+   * Destroys an object
+   * @param instance Object to destroy
+   * @param recursive If true, all children will be destroyed as well. Default: true
    */
   static destroy(e, i = !0) {
     return ss(e, i);
   }
   /**
-   * Add an object to parent and also ensure all components are being registered
+   * Adds an object to parent and ensures all components are properly registered
+   * @param instance Object to add
+   * @param parent Parent to add the object to
+   * @param context Optional context to use
    */
   static add(e, i, s) {
     if (!(!e || !i)) {
@@ -11866,6 +11906,7 @@ class C extends D {
   }
   /**
    * Removes the object from its parent and deactivates all of its components
+   * @param instance Object to remove
    */
   static remove(e) {
     var i;
@@ -11873,13 +11914,21 @@ class C extends D {
       kP(s);
     }, !0));
   }
-  /** Invokes a method on all components including children (if a method with that name exists) */
+  /**
+   * Invokes a method on all components including children (if a method with that name exists)
+   * @param go GameObject to invoke the method on
+   * @param functionName Name of the method to invoke
+   * @param args Arguments to pass to the method
+   */
   static invokeOnChildren(e, i, ...s) {
     this.invoke(e, i, !0, s);
   }
-  /** Invokes a method on all components that have a method matching the provided name
-   * @param go object to invoke the method on all components
-   * @param functionName name of the method to invoke
+  /**
+   * Invokes a method on all components that have a method matching the provided name
+   * @param go GameObject to invoke the method on
+   * @param functionName Name of the method to invoke
+   * @param children Whether to invoke on children as well
+   * @param args Arguments to pass to the method
    */
   static invoke(e, i, s = !1, ...o) {
     e && this.foreachComponent(e, (a) => {
@@ -11893,66 +11942,143 @@ class C extends D {
     return Ji(e, i, s, { callAwake: o });
   }
   /**
-   * Add a new component (or move an existing component) to the provided object
-   * @param go object to add the component to
-   * @param instanceOrType if an instance is provided it will be moved to the new object, if a type is provided a new instance will be created and moved to the new object
-   * @param init optional init object to initialize the component with
-   * @param callAwake if true, the component will be added and awake will be called immediately
+   * Adds a new component (or moves an existing component) to the provided object
+   * @param go Object to add the component to
+   * @param instanceOrType If an instance is provided it will be moved to the new object, if a type is provided a new instance will be created
+   * @param init Optional init object to initialize the component with
+   * @param opts Optional options for adding the component
+   * @returns The added or moved component
    */
   static addComponent(e, i, s, o) {
     return Ji(e, i, s, o);
   }
   /**
-   * Moves a component to a new object  
-   * @param go component to move the component to
-   * @param instance component to move to the GO
+   * Moves a component to a new object
+   * @param go GameObject to move the component to
+   * @param instance Component to move
+   * @returns The moved component
    */
   static moveComponent(e, i) {
     return Ji(e, i);
   }
-  /** Removes a component from its object
-   * @param instance component to remove
+  /**
+   * Removes a component from its object
+   * @param instance Component to remove
+   * @returns The removed component
    */
   static removeComponent(e) {
     return wv(e.gameObject, e), e;
   }
+  /**
+   * Gets or adds a component of the specified type
+   * @param go GameObject to get or add the component to
+   * @param typeName Constructor of the component type
+   * @returns The existing or newly added component
+   */
   static getOrAddComponent(e, i) {
     return Bu(e, i);
   }
-  /** Gets a component on the provided object */
+  /**
+   * Gets a component on the provided object
+   * @param go GameObject to get the component from
+   * @param typeName Constructor of the component type
+   * @returns The component if found, otherwise null
+   */
   static getComponent(e, i) {
     return e === null ? null : il(e, i);
   }
+  /**
+   * Gets all components of the specified type on the provided object
+   * @param go GameObject to get the components from
+   * @param typeName Constructor of the component type
+   * @param arr Optional array to populate with the components
+   * @returns Array of components
+   */
   static getComponents(e, i, s = null) {
     return e === null ? s ?? [] : Fu(e, i, s);
   }
+  /**
+   * Finds an object or component by its unique identifier
+   * @param guid Unique identifier to search for
+   * @param hierarchy Root object to search in
+   * @returns The found GameObject or Component, or null/undefined if not found
+   */
   static findByGuid(e, i) {
     return Cv(e, i);
   }
+  /**
+   * Finds the first object of the specified component type in the scene
+   * @param typeName Constructor of the component type
+   * @param context Context or root object to search in
+   * @param includeInactive Whether to include inactive objects in the search
+   * @returns The first matching component if found, otherwise null
+   */
   static findObjectOfType(e, i, s = !0) {
     return Ag(e, i ?? ee.Current, s);
   }
+  /**
+   * Finds all objects of the specified component type in the scene
+   * @param typeName Constructor of the component type
+   * @param context Context or root object to search in
+   * @returns Array of matching components
+   */
   static findObjectsOfType(e, i) {
     const s = [];
     return fO(e, s, i), s;
   }
+  /**
+   * Gets a component of the specified type in the gameObject's children hierarchy
+   * @param go GameObject to search in
+   * @param typeName Constructor of the component type
+   * @returns The first matching component if found, otherwise null
+   */
   static getComponentInChildren(e, i) {
     return zu(e, i);
   }
+  /**
+   * Gets all components of the specified type in the gameObject's children hierarchy
+   * @param go GameObject to search in
+   * @param typeName Constructor of the component type
+   * @param arr Optional array to populate with the components
+   * @returns Array of components
+   */
   static getComponentsInChildren(e, i, s = null) {
     return Kc(e, i, s ?? void 0);
   }
+  /**
+   * Gets a component of the specified type in the gameObject's parent hierarchy
+   * @param go GameObject to search in
+   * @param typeName Constructor of the component type
+   * @returns The first matching component if found, otherwise null
+   */
   static getComponentInParent(e, i) {
     return Wd(e, i);
   }
+  /**
+   * Gets all components of the specified type in the gameObject's parent hierarchy
+   * @param go GameObject to search in
+   * @param typeName Constructor of the component type
+   * @param arr Optional array to populate with the components
+   * @returns Array of components
+   */
   static getComponentsInParent(e, i, s = null) {
     return Tg(e, i, s);
   }
+  /**
+   * Gets all components on the gameObject
+   * @param go GameObject to get components from
+   * @returns Array of all components
+   */
   static getAllComponents(e) {
     var o;
     const i = (o = e.userData) == null ? void 0 : o.components;
     return i ? [...i] : [];
   }
+  /**
+   * Iterates through all components on the gameObject
+   * @param go GameObject to iterate components on
+   * @returns Generator yielding each component
+   */
   static *iterateComponents(e) {
     var s;
     const i = (s = e == null ? void 0 : e.userData) == null ? void 0 : s.components;
@@ -11966,11 +12092,20 @@ const Mc = class {
   constructor(t) {
     r(this, "__context");
     r(this, "__name");
-    /** the object this component is attached to. Note that this is a threejs Object3D with some additional features */
+    /**
+     * Reference to the GameObject this component is attached to
+     * This is a three.js Object3D with additional GameObject functionality
+     */
     r(this, "gameObject");
-    /** the unique identifier for this component */
+    /**
+     * Unique identifier for this component instance,
+     * used for finding and tracking components
+     */
     r(this, "guid", "invalid");
-    /** holds the source identifier this object was created with/from (e.g. if it was part of a glTF file the sourceId holds the url to the glTF) */
+    /**
+     * Identifier for the source asset that created this component.
+     * For example, URL to the glTF file this component was loaded from
+     */
     r(this, "sourceId");
     /** @internal */
     r(this, "__didAwake", !1);
@@ -11983,31 +12118,49 @@ const Mc = class {
     /** @internal */
     r(this, "__destroyed", !1);
     // EventTarget implementation:
+    /** 
+     * Storage for event listeners registered to this component
+     * @private
+     */
     r(this, "_eventListeners", /* @__PURE__ */ new Map());
     this.__didAwake = !1, this.__didStart = !1, this.__didEnable = !1, this.__isEnabled = void 0, this.__destroyed = !1, this._internalInit(t);
   }
-  /** @internal */
+  /** 
+   * Indicates whether this object is a component
+   * @internal 
+   */
   get isComponent() {
     return !0;
   }
-  /** Use the context to get access to many Needle Engine features and use physics, timing, access the camera or scene */
+  /**
+   * The context this component belongs to, providing access to the runtime environment
+   * including physics, timing utilities, camera, and scene
+   */
   get context() {
     return this.__context ?? ee.Current;
   }
   set context(t) {
     this.__context = t;
   }
-  /** shorthand for `this.context.scene`
-   * @returns the scene of the context  */
+  /**
+   * Shorthand accessor for the current scene from the context
+   * @returns The scene this component belongs to
+   */
   get scene() {
     return this.context.scene;
   }
-  /** @returns the layer of the gameObject this component is attached to */
+  /**
+   * The layer value of the GameObject this component is attached to
+   * Used for visibility and physics filtering
+   */
   get layer() {
     var t, e;
     return (e = (t = this.gameObject) == null ? void 0 : t.userData) == null ? void 0 : e.layer;
   }
-  /** @returns the name of the gameObject this component is attached to */
+  /**
+   * The name of the GameObject this component is attached to
+   * Used for debugging and finding objects
+   */
   get name() {
     var t, e;
     return (t = this.gameObject) != null && t.name ? this.gameObject.name : (e = this.gameObject) == null ? void 0 : e.userData.name;
@@ -12015,7 +12168,10 @@ const Mc = class {
   set name(t) {
     this.gameObject ? (this.gameObject.userData || (this.gameObject.userData = {}), this.gameObject.userData.name = t, this.__name = t) : this.__name = t;
   }
-  /** @returns the tag of the gameObject this component is attached to */
+  /**
+   * The tag of the GameObject this component is attached to
+   * Used for categorizing objects and efficient lookup
+   */
   get tag() {
     var t;
     return (t = this.gameObject) == null ? void 0 : t.userData.tag;
@@ -12023,7 +12179,10 @@ const Mc = class {
   set tag(t) {
     this.gameObject && (this.gameObject.userData || (this.gameObject.userData = {}), this.gameObject.userData.tag = t);
   }
-  /** Is the gameObject marked as static */
+  /**
+   * Indicates whether the GameObject is marked as static
+   * Static objects typically don't move and can be optimized by the engine
+   */
   get static() {
     var t;
     return (t = this.gameObject) == null ? void 0 : t.userData.static;
@@ -12034,7 +12193,11 @@ const Mc = class {
   // get hideFlags(): HideFlags {
   //     return this.gameObject?.hideFlags;
   // }
-  /** @returns true if the object is enabled and active in the hierarchy */
+  /**
+   * Checks if this component is currently active (enabled and part of an active GameObject hierarchy)
+   * Components that are inactive won't receive lifecycle method calls
+   * @returns True if the component is enabled and all parent GameObjects are active
+   */
   get activeAndEnabled() {
     return !(this.destroyed || this.__isEnabled === !1 || !this.__isActiveInHierarchy);
   }
@@ -12050,39 +12213,60 @@ const Mc = class {
   set __isActiveInHierarchy(t) {
     this.gameObject && (this.gameObject[yo] = t);
   }
-  /** called once when the component becomes active for the first time (once per component)   
-   * This is the first callback to be called */
+  /**
+   * Called once when the component becomes active for the first time.
+   * This is the first lifecycle callback to be invoked
+   */
   awake() {
   }
-  /** called every time when the component gets enabled (this is invoked after awake and before start)   
-   * or when it becomes active in the hierarchy (e.g. if a parent object or this.gameObject gets set to visible)
-  */
+  /**
+   * Called every time the component becomes enabled or active in the hierarchy.
+   * Invoked after {@link awake} and before {@link start}.
+   */
   onEnable() {
   }
-  /** called every time the component gets disabled or if a parent object (or this.gameObject) gets set to invisible */
+  /**
+   * Called every time the component becomes disabled or inactive in the hierarchy.
+   * Invoked when the component or any parent GameObject becomes invisible
+   */
   onDisable() {
   }
-  /** Called when the component gets destroyed */
+  /**
+   * Called when the component is destroyed.
+   * Use for cleanup operations like removing event listeners
+   */
   onDestroy() {
     this.__destroyed = !0;
   }
-  /** starts a coroutine (javascript generator function)   
-   * `yield` will wait for the next frame:  
-   * - Use `yield WaitForSeconds(1)` to wait for 1 second.
-   * - Use `yield WaitForFrames(10)` to wait for 10 frames.
-   * - Use `yield new Promise(...)` to wait for a promise to resolve.  
-   * @param routine generator function to start
-   * @param evt event to register the coroutine for (default: FrameEvent.Update). Note that all coroutine FrameEvent callbacks are invoked after the matching regular component callbacks. For example `FrameEvent.Update` will be called after regular component `update()` methods)  
-   * @returns the generator function (use it to stop the coroutine with `stopCoroutine`)
-   * @example 
+  /**
+   * Starts a coroutine that can yield to wait for events.
+   * Coroutines allow for time-based sequencing of operations without blocking.
+   * Coroutines are based on generator functions, a JavaScript language feature. 
+   * 
+   * @param routine Generator function to start
+   * @param evt Event to register the coroutine for (default: FrameEvent.Update)
+   * @returns The generator function that can be used to stop the coroutine
+   * @example
+   * Time-based sequencing of operations
+   * ```ts
+   * *myCoroutine() {
+   *   yield WaitForSeconds(1); // wait for 1 second
+   *   yield WaitForFrames(10); // wait for 10 frames
+   *   yield new Promise(resolve => setTimeout(resolve, 1000)); // wait for a promise to resolve
+   * }
+   * ```
+   * @example
+   * Coroutine that logs a message every 5 frames
    * ```ts
-   * onEnable() { this.startCoroutine(this.myCoroutine()); }
+   * onEnable() {
+   *   this.startCoroutine(this.myCoroutine());
+   * }
    * private *myCoroutine() {
-   *    while(this.activeAndEnabled) {
-   *       console.log("Hello World", this.context.time.frame);
-   *       // wait for 5 frames
-   *       for(let i = 0; i < 5; i++) yield;
-   *    }
+   *   while(this.activeAndEnabled) {
+   *     console.log("Hello World", this.context.time.frame);
+   *     // wait for 5 frames
+   *     for(let i = 0; i < 5; i++) yield;
+   *   }
    * }
    * ```
    */
@@ -12090,19 +12274,23 @@ const Mc = class {
     return this.context.registerCoroutineUpdate(this, t, e);
   }
   /**
-   * Stop a coroutine that was previously started with `startCoroutine`
-   * @param routine the routine to be stopped
-   * @param evt the frame event to unregister the routine from (default: FrameEvent.Update)
+   * Stops a coroutine that was previously started with startCoroutine
+   * @param routine The routine to be stopped
+   * @param evt The frame event the routine was registered with
    */
   stopCoroutine(t, e = Me.Update) {
     this.context.unregisterCoroutineUpdate(t, e);
   }
-  /** @returns true if this component was destroyed (`this.destroy()`) or the whole object this component was part of */
+  /**
+   * Checks if this component has been destroyed
+   * @returns True if the component or its GameObject has been destroyed
+   */
   get destroyed() {
     return this.__destroyed;
   }
   /**
-   * Destroys this component (and removes it from the object)
+   * Destroys this component and removes it from its GameObject
+   * After destruction, the component will no longer receive lifecycle callbacks
    */
   destroy() {
     this.__destroyed || this.__internalDestroy();
@@ -12115,6 +12303,11 @@ const Mc = class {
   __internalNewInstanceCreated(t) {
     return this.__didAwake = !1, this.__didStart = !1, this.__didEnable = !1, this.__isEnabled = void 0, this.__destroyed = !1, this._internalInit(t), this;
   }
+  /**
+   * Initializes component properties from an initialization object
+   * @param init Object with properties to copy to this component
+   * @internal
+   */
   _internalInit(t) {
     if (typeof t == "object")
       for (const e of Object.keys(t)) {
@@ -12149,6 +12342,10 @@ const Mc = class {
     var t;
     this.__destroyed || (this.__destroyed = !0, this.__didAwake && ((t = this.onDestroy) == null || t.call(this), this.dispatchEvent(new CustomEvent("destroyed", { detail: this }))), uO(this));
   }
+  /**
+   * Controls whether this component is enabled
+   * Disabled components don't receive lifecycle callbacks
+   */
   get enabled() {
     return typeof this.__isEnabled == "boolean" ? this.__isEnabled : !0;
   }
@@ -12163,63 +12360,129 @@ const Mc = class {
     }
     t ? this.__internalEnable() : this.__internalDisable();
   }
+  /**
+   * Gets the position of this component's GameObject in world space
+   */
   get worldPosition() {
     return te(this.gameObject);
   }
+  /**
+   * Sets the position of this component's GameObject in world space
+   * @param val The world position vector to set
+   */
   set worldPosition(t) {
     yt(this.gameObject, t);
   }
+  /**
+   * Sets the position of this component's GameObject in world space using individual coordinates
+   * @param x X-coordinate in world space
+   * @param y Y-coordinate in world space
+   * @param z Z-coordinate in world space
+   */
   setWorldPosition(t, e, i) {
     Va(this.gameObject, t, e, i);
   }
+  /**
+   * Gets the rotation of this component's GameObject in world space as a quaternion
+   */
   get worldQuaternion() {
     return Pe(this.gameObject);
   }
+  /**
+   * Sets the rotation of this component's GameObject in world space using a quaternion
+   * @param val The world rotation quaternion to set
+   */
   set worldQuaternion(t) {
     vs(this.gameObject, t);
   }
+  /**
+   * Sets the rotation of this component's GameObject in world space using quaternion components
+   * @param x X component of the quaternion
+   * @param y Y component of the quaternion
+   * @param z Z component of the quaternion
+   * @param w W component of the quaternion
+   */
   setWorldQuaternion(t, e, i, s) {
     I0(this.gameObject, t, e, i, s);
   }
-  // world euler (in radians)
+  /**
+   * Gets the rotation of this component's GameObject in world space as Euler angles (in radians)
+   */
   get worldEuler() {
     return D0(this.gameObject);
   }
-  // world euler (in radians)
+  /**
+   * Sets the rotation of this component's GameObject in world space using Euler angles (in radians)
+   * @param val The world rotation Euler angles to set
+   */
   set worldEuler(t) {
     L0(this.gameObject, t);
   }
-  // returns rotation in degrees
+  /**
+   * Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)
+   */
   get worldRotation() {
     return this.gameObject.worldRotation;
   }
+  /**
+   * Sets the rotation of this component's GameObject in world space using Euler angles (in degrees)
+   * @param val The world rotation vector to set (in degrees)
+   */
   set worldRotation(t) {
     this.setWorldRotation(t.x, t.y, t.z, !0);
   }
+  /**
+   * Sets the rotation of this component's GameObject in world space using individual Euler angles
+   * @param x X-axis rotation
+   * @param y Y-axis rotation
+   * @param z Z-axis rotation
+   * @param degrees Whether the values are in degrees (true) or radians (false)
+   */
   setWorldRotation(t, e, i, s = !0) {
     Eu(this.gameObject, t, e, i, s);
   }
-  /** Forward (0,0,-1) vector in world space */
+  /**
+   * Gets the forward direction vector (0,0,-1) of this component's GameObject in world space
+   */
   get forward() {
     return Mc._forward.set(0, 0, -1).applyQuaternion(this.worldQuaternion);
   }
-  /** Right (1,0,0) vector in world space */
+  /**
+   * Gets the right direction vector (1,0,0) of this component's GameObject in world space
+   */
   get right() {
     return Mc._right.set(1, 0, 0).applyQuaternion(this.worldQuaternion);
   }
-  /** Up (0,1,0) vector in world space */
+  /**
+   * Gets the up direction vector (0,1,0) of this component's GameObject in world space
+   */
   get up() {
     return Mc._up.set(0, 1, 0).applyQuaternion(this.worldQuaternion);
   }
+  /**
+   * Registers an event listener for the specified event type
+   * @param type The event type to listen for
+   * @param listener The callback function to execute when the event occurs
+   */
   addEventListener(t, e) {
     this._eventListeners[t] = this._eventListeners[t] || [], this._eventListeners[t].push(e);
   }
+  /**
+   * Removes a previously registered event listener
+   * @param type The event type the listener was registered for
+   * @param listener The callback function to remove
+   */
   removeEventListener(t, e) {
     if (!this._eventListeners[t])
       return;
     const i = this._eventListeners[t].indexOf(e);
     i >= 0 && this._eventListeners[t].splice(i, 1);
   }
+  /**
+   * Dispatches an event to all registered listeners
+   * @param evt The event object to dispatch
+   * @returns Always returns false (standard implementation of EventTarget)
+   */
   dispatchEvent(t) {
     if (!t || !this._eventListeners[t.type])
       return !1;
@@ -12758,11 +13021,18 @@ const rt = S("debuganimatorcontroller"), zh = S("debugrootmotion");
 class es {
   constructor(t) {
     r(this, "_speed", 1);
-    /** The normalized time of the start state. This is used to determine the start time of the first state. */
+    /**
+     * The normalized time (0-1) to start playing the first state at.
+     * This affects the initial state when the animator is first enabled.
+     */
     r(this, "normalizedStartOffset", 0);
-    /** the animator that this controller is bound to */
+    /**
+     * The Animator component this controller is bound to.
+     */
     r(this, "animator");
-    /** the model that this controller is based on */
+    /**
+     * The data model describing the animation states and transitions.
+     */
     r(this, "model");
     r(this, "_mixer");
     r(this, "_activeState");
@@ -12775,11 +13045,14 @@ class es {
     r(this, "rootMotionHandler");
     this.model = t, rt && console.log(this);
   }
-  /** Create an animatorcontroller. States are created from the clips array.
-   * @param clips the clips to assign to the controller
-   * @param options options to control the creation of the controller. 
-   * @returns the created animator controller
-  */
+  /**
+   * Creates an AnimatorController from a set of animation clips.
+   * Each clip becomes a state in the controller's state machine.
+   * 
+   * @param clips - The animation clips to use for creating states
+   * @param options - Configuration options for the controller including looping behavior and transitions
+   * @returns A new AnimatorController instance
+   */
   static createFromClips(t, e = { looping: !1, autoTransition: !0, transitionDuration: 0 }) {
     const i = [];
     for (let a = 0; a < t.length; a++) {
@@ -12824,6 +13097,14 @@ class es {
     };
     return new es(s);
   }
+  /**
+   * Plays an animation state by name or hash.
+   * 
+   * @param name - The name or hash identifier of the state to play
+   * @param layerIndex - The layer index (defaults to 0)
+   * @param normalizedTime - The normalized time to start the animation from (0-1)
+   * @param durationInSec - Transition duration in seconds
+   */
   play(t, e = -1, i = Number.NEGATIVE_INFINITY, s = 0) {
     if (e < 0)
       e = 0;
@@ -12839,55 +13120,117 @@ class es {
       }
     console.warn("Could not find " + t + " to play");
   }
+  /**
+   * Resets the controller to its initial state.
+   */
   reset() {
     this.setStartTransition();
   }
+  /**
+   * Sets a boolean parameter value by name or hash.
+   * 
+   * @param name - The name or hash identifier of the parameter
+   * @param value - The boolean value to set
+   */
   setBool(t, e) {
     var s, o;
     const i = typeof t == "string" ? "name" : "hash";
     return (o = (s = this.model) == null ? void 0 : s.parameters) == null ? void 0 : o.filter((a) => a[i] === t).forEach((a) => a.value = e);
   }
+  /**
+   * Gets a boolean parameter value by name or hash.
+   * 
+   * @param name - The name or hash identifier of the parameter
+   * @returns The boolean value of the parameter, or false if not found
+   */
   getBool(t) {
     var i, s, o;
     const e = typeof t == "string" ? "name" : "hash";
     return ((o = (s = (i = this.model) == null ? void 0 : i.parameters) == null ? void 0 : s.find((a) => a[e] === t)) == null ? void 0 : o.value) ?? !1;
   }
+  /**
+   * Sets a float parameter value by name or hash.
+   * 
+   * @param name - The name or hash identifier of the parameter
+   * @param val - The float value to set
+   * @returns True if the parameter was found and set, false otherwise
+   */
   setFloat(t, e) {
     var o, a;
     const i = typeof t == "string" ? "name" : "hash", s = (a = (o = this.model) == null ? void 0 : o.parameters) == null ? void 0 : a.filter((l) => l[i] === t);
     return s.forEach((l) => l.value = e), (s == null ? void 0 : s.length) > 0;
   }
+  /**
+   * Gets a float parameter value by name or hash.
+   * 
+   * @param name - The name or hash identifier of the parameter
+   * @returns The float value of the parameter, or 0 if not found
+   */
   getFloat(t) {
     var i, s, o;
     const e = typeof t == "string" ? "name" : "hash";
     return ((o = (s = (i = this.model) == null ? void 0 : i.parameters) == null ? void 0 : s.find((a) => a[e] === t)) == null ? void 0 : o.value) ?? 0;
   }
+  /**
+   * Sets an integer parameter value by name or hash.
+   * 
+   * @param name - The name or hash identifier of the parameter
+   * @param val - The integer value to set
+   */
   setInteger(t, e) {
     var s, o;
     const i = typeof t == "string" ? "name" : "hash";
     return (o = (s = this.model) == null ? void 0 : s.parameters) == null ? void 0 : o.filter((a) => a[i] === t).forEach((a) => a.value = e);
   }
+  /**
+   * Gets an integer parameter value by name or hash.
+   * 
+   * @param name - The name or hash identifier of the parameter
+   * @returns The integer value of the parameter, or 0 if not found
+   */
   getInteger(t) {
     var i, s, o;
     const e = typeof t == "string" ? "name" : "hash";
     return ((o = (s = (i = this.model) == null ? void 0 : i.parameters) == null ? void 0 : s.find((a) => a[e] === t)) == null ? void 0 : o.value) ?? 0;
   }
+  /**
+   * Sets a trigger parameter to active (true).
+   * Trigger parameters are automatically reset after they are consumed by a transition.
+   * 
+   * @param name - The name or hash identifier of the trigger parameter
+   */
   setTrigger(t) {
     var i, s;
     rt && console.log("SET TRIGGER", t);
     const e = typeof t == "string" ? "name" : "hash";
     return (s = (i = this.model) == null ? void 0 : i.parameters) == null ? void 0 : s.filter((o) => o[e] === t).forEach((o) => o.value = !0);
   }
+  /**
+   * Resets a trigger parameter to inactive (false).
+   * 
+   * @param name - The name or hash identifier of the trigger parameter
+   */
   resetTrigger(t) {
     var i, s;
     const e = typeof t == "string" ? "name" : "hash";
     return (s = (i = this.model) == null ? void 0 : i.parameters) == null ? void 0 : s.filter((o) => o[e] === t).forEach((o) => o.value = !1);
   }
+  /**
+   * Gets the current state of a trigger parameter.
+   * 
+   * @param name - The name or hash identifier of the trigger parameter
+   * @returns The boolean state of the trigger, or false if not found
+   */
   getTrigger(t) {
     var i, s, o;
     const e = typeof t == "string" ? "name" : "hash";
     return ((o = (s = (i = this.model) == null ? void 0 : i.parameters) == null ? void 0 : s.find((a) => a[e] === t)) == null ? void 0 : o.value) ?? !1;
   }
+  /**
+   * Checks if the controller is currently in a transition between states.
+   * 
+   * @returns True if a transition is in progress, false otherwise
+   */
   isInTransition() {
     return this._activeStates.length > 1;
   }
@@ -12895,10 +13238,22 @@ class es {
   setSpeed(t) {
     this._speed = t;
   }
-  /**@deprecated use findState */
+  /**
+   * Finds an animation state by name or hash.
+   * @deprecated Use findState instead
+   * 
+   * @param name - The name or hash identifier of the state to find
+   * @returns The found state or null if not found
+   */
   FindState(t) {
     return this.findState(t);
   }
+  /**
+   * Finds an animation state by name or hash.
+   * 
+   * @param name - The name or hash identifier of the state to find
+   * @returns The found state or null if not found
+   */
   findState(t) {
     if (!t)
       return null;
@@ -12910,9 +13265,11 @@ class es {
     }
     return null;
   }
-  /** Get the current state info 
-   * @returns the current state info or null if no state is active
-  */
+  /**
+   * Gets information about the current playing animation state.
+   * 
+   * @returns An AnimatorStateInfo object with data about the current state, or null if no state is active
+   */
   getCurrentStateInfo() {
     if (!this._activeState)
       return null;
@@ -12922,27 +13279,33 @@ class es {
     const e = this._activeState.motion.clip.duration, i = e <= 0 ? 0 : Math.abs(t.time / e);
     return new Fh(this._activeState, i, e, this._speed);
   }
-  /** Get the current action (shorthand for activeState.motion.action)  
-   * @returns the current action that is playing. This is the action that is currently transitioning to or playing.
-   * If no action is playing null is returned.
-   **/
+  /**
+   * Gets the animation action currently playing.
+   * 
+   * @returns The current animation action, or null if no action is playing
+   */
   get currentAction() {
     if (!this._activeState)
       return null;
     const t = this._activeState.motion.action;
     return t || null;
   }
-  /** Get the context of the animator */
+  /**
+   * Gets the engine context from the bound animator.
+   */
   get context() {
     var t;
     return (t = this.animator) == null ? void 0 : t.context;
   }
-  /** Get the animation mixer that is used to play the animations */
+  /**
+   * Gets the animation mixer used by this controller.
+   */
   get mixer() {
     return this._mixer;
   }
   /**
-   * Clears the animation mixer and unregisters it from the context.
+   * Cleans up resources used by this controller.
+   * Stops all animations and unregisters the mixer from the animation system.
    */
   dispose() {
     var t;
@@ -12956,12 +13319,22 @@ class es {
   // applyRootMotion(obj: Object3D) {
   //     // this.internalApplyRootMotion(obj);
   // }
-  /** Bind the animator to the controller. Only one animator can be bound to a controller at a time. */
+  /**
+   * Binds this controller to an animator component.
+   * Creates a new animation mixer and sets up animation actions.
+   * 
+   * @param animator - The animator to bind this controller to
+   */
   bind(t) {
     var e, i;
     t ? this.animator !== t && (this._mixer && (this._mixer.stopAllAction(), (e = this.context) == null || e.animations.unregisterAnimationMixer(this._mixer)), this.animator = t, this._mixer = new rg(this.animator.gameObject), (i = this.context) == null || i.animations.registerAnimationMixer(this._mixer), this.createActions(this.animator)) : console.error("AnimatorController.bind: animator is null");
   }
-  /** Create a clone of the controller. This will clone the model but not the runtime state. */
+  /**
+   * Creates a deep copy of this controller.
+   * Clones the model data but does not copy runtime state.
+   * 
+   * @returns A new AnimatorController instance with the same configuration
+   */
   clone() {
     if (typeof this.model == "string")
       return console.warn("AnimatorController has not been resolved, can not create model from string", this.model), null;
@@ -12969,7 +13342,12 @@ class es {
     const t = Ru(this.model, (i, s, o) => o == null ? !0 : !(o.type === "Object3D" || o.isObject3D === !0 || uC(o) || o.tracks !== void 0 || o instanceof es));
     return console.assert(t !== this.model), new es(t);
   }
-  /** Called by the animator. This will update the active states and transitions as well as the animation mixer. */
+  /**
+   * Updates the controller's state machine and animations.
+   * Called each frame by the animator component.
+   * 
+   * @param weight - The weight to apply to the animations (for blending)
+   */
   update(t) {
     var i, s;
     if (!this.animator)
@@ -12978,9 +13356,11 @@ class es {
     const e = this.animator.context.time.deltaTime;
     this.animator.applyRootMotion && ((i = this.rootMotionHandler) == null || i.onBeforeUpdate(t)), this._mixer.update(e), this.animator.applyRootMotion && ((s = this.rootMotionHandler) == null || s.onAfterUpdate(t));
   }
-  /** Get the currently active state playing
-   * @returns the currently active state or undefined if no state is active
-   **/
+  /**
+   * Gets the currently active animation state.
+   * 
+   * @returns The active state or undefined if no state is active
+   */
   get activeState() {
     return this._activeState;
   }
@@ -13185,6 +13565,10 @@ Exit Time: ` + d, a.hasExitTime);
       }
     }
   }
+  /**
+   * Yields all animation actions managed by this controller.
+   * Iterates through all states in all layers and returns their actions.
+   */
   *enumerateActions() {
     if (this.model.layers)
       for (const t of this.model.layers) {
@@ -13382,6 +13766,9 @@ class zt extends I {
     // so they effectively share the same mixer. There might be cases still where not the same mixer is being used but then the animation track prints an error in dev
     r(this, "_initializeWithRuntimeAnimatorController");
   }
+  /** 
+   * Identifies this component as an animation component in the engine
+   */
   get isAnimationComponent() {
     return !0;
   }
@@ -13389,29 +13776,40 @@ class zt extends I {
     var i;
     this._animatorController && this._animatorController.model === e || (e ? e instanceof es ? (e.animator && e.animator !== this && (console.warn("AnimatorController can not be bound to multiple animators", (i = e.model) == null ? void 0 : i.name), e.model || console.error("AnimatorController has no model"), e = new es(e.model)), this._animatorController = e, this._animatorController.bind(this)) : (zi && console.log("Assign animator controller", e, this), this._animatorController = new es(e), this.__didAwake && this._animatorController.bind(this)) : this._animatorController = null);
   }
+  /**
+   * Gets the current animator controller instance
+   * @returns The current animator controller or null if none is assigned
+   */
   get runtimeAnimatorController() {
     return this._animatorController;
   }
-  /** The current state info of the animator.   
-   * If you just want to access the currently playing animation action you can use currentAction
-   * @returns {AnimatorStateInfo} The current state info of the animator or null if no state is playing
-  */
+  /** 
+   * Retrieves information about the current animation state
+   * @returns The current state information, or undefined if no state is playing
+   */
   getCurrentStateInfo() {
     var e;
     return (e = this.runtimeAnimatorController) == null ? void 0 : e.getCurrentStateInfo();
   }
-  /** The current action playing. It can be used to modify the action   
-   * @returns {AnimationAction | null} The current action playing or null if no state is playing
-  */
+  /** 
+   * The currently playing animation action that can be used to modify animation properties
+   * @returns The current animation action, or null if no animation is playing
+   */
   get currentAction() {
     var e;
     return ((e = this.runtimeAnimatorController) == null ? void 0 : e.currentAction) || null;
   }
-  /** @returns {boolean} True if parameters have been changed */
+  /** 
+   * Indicates whether animation parameters have been modified since the last update
+   * @returns True if parameters have been changed
+   */
   get parametersAreDirty() {
     return this._parametersAreDirty;
   }
-  /** @returns {boolean} True if the animator has been changed */
+  /** 
+   * Indicates whether the animator state has changed since the last update
+   * @returns True if the animator has been changed
+   */
   get isDirty() {
     return this._isDirty;
   }
@@ -13419,13 +13817,13 @@ class zt extends I {
   Play(e, i = -1, s = Number.NEGATIVE_INFINITY, o = 0) {
     this.play(e, i, s, o);
   }
-  /** Plays an animation on the animator
-   * @param {string | number} name The name of the animation to play. Can also be the hash of the animation
-   * @param {number} layer The layer to play the animation on. Default is -1
-   * @param {number} normalizedTime The normalized time to start the animation at. Default is Number.NEGATIVE_INFINITY
-   * @param {number} transitionDurationInSec The duration of the transition to the new animation. Default is 0
-   * @returns {void}
-   * */
+  /** 
+   * Plays an animation on the animator
+   * @param name The name or hash of the animation to play
+   * @param layer The layer to play the animation on (-1 for default layer)
+   * @param normalizedTime The time position to start playing (0-1 range, NEGATIVE_INFINITY for current position)
+   * @param transitionDurationInSec The duration of the blend transition in seconds
+   */
   play(e, i = -1, s = Number.NEGATIVE_INFINITY, o = 0) {
     var a;
     (a = this.runtimeAnimatorController) == null || a.play(e, i, s, o), this._isDirty = !0;
@@ -13434,7 +13832,9 @@ class zt extends I {
   Reset() {
     this.reset();
   }
-  /** Resets the animatorcontroller */
+  /** 
+   * Resets the animator controller to its initial state
+   */
   reset() {
     var e;
     (e = this._animatorController) == null || e.reset(), this._isDirty = !0;
@@ -13443,6 +13843,11 @@ class zt extends I {
   SetBool(e, i) {
     this.setBool(e, i);
   }
+  /**
+   * Sets a boolean parameter in the animator
+   * @param name The name or hash of the parameter
+   * @param value The boolean value to set
+   */
   setBool(e, i) {
     var s, o;
     zi && console.log("setBool", e, i), ((s = this.runtimeAnimatorController) == null ? void 0 : s.getBool(e)) !== i && (this._parametersAreDirty = !0), (o = this.runtimeAnimatorController) == null || o.setBool(e, i);
@@ -13451,11 +13856,20 @@ class zt extends I {
   GetBool(e) {
     return this.getBool(e);
   }
+  /**
+   * Gets a boolean parameter from the animator
+   * @param name The name or hash of the parameter
+   * @returns The value of the boolean parameter, or false if not found
+   */
   getBool(e) {
     var s;
     const i = ((s = this.runtimeAnimatorController) == null ? void 0 : s.getBool(e)) ?? !1;
     return zi && console.log("getBool", e, i), i;
   }
+  /**
+   * Toggles a boolean parameter between true and false
+   * @param name The name or hash of the parameter
+   */
   toggleBool(e) {
     this.setBool(e, !this.getBool(e));
   }
@@ -13463,6 +13877,11 @@ class zt extends I {
   SetFloat(e, i) {
     this.setFloat(e, i);
   }
+  /**
+   * Sets a float parameter in the animator
+   * @param name The name or hash of the parameter
+   * @param val The float value to set
+   */
   setFloat(e, i) {
     var s, o;
     ((s = this.runtimeAnimatorController) == null ? void 0 : s.getFloat(e)) !== i && (this._parametersAreDirty = !0), zi && console.log("setFloat", e, i), (o = this.runtimeAnimatorController) == null || o.setFloat(e, i);
@@ -13471,6 +13890,11 @@ class zt extends I {
   GetFloat(e) {
     return this.getFloat(e);
   }
+  /**
+   * Gets a float parameter from the animator
+   * @param name The name or hash of the parameter
+   * @returns The value of the float parameter, or -1 if not found
+   */
   getFloat(e) {
     var s;
     const i = ((s = this.runtimeAnimatorController) == null ? void 0 : s.getFloat(e)) ?? -1;
@@ -13480,6 +13904,11 @@ class zt extends I {
   SetInteger(e, i) {
     this.setInteger(e, i);
   }
+  /**
+   * Sets an integer parameter in the animator
+   * @param name The name or hash of the parameter
+   * @param val The integer value to set
+   */
   setInteger(e, i) {
     var s, o;
     ((s = this.runtimeAnimatorController) == null ? void 0 : s.getInteger(e)) !== i && (this._parametersAreDirty = !0), zi && console.log("setInteger", e, i), (o = this.runtimeAnimatorController) == null || o.setInteger(e, i);
@@ -13488,6 +13917,11 @@ class zt extends I {
   GetInteger(e) {
     return this.getInteger(e);
   }
+  /**
+   * Gets an integer parameter from the animator
+   * @param name The name or hash of the parameter
+   * @returns The value of the integer parameter, or -1 if not found
+   */
   getInteger(e) {
     var s;
     const i = ((s = this.runtimeAnimatorController) == null ? void 0 : s.getInteger(e)) ?? -1;
@@ -13497,6 +13931,10 @@ class zt extends I {
   SetTrigger(e) {
     this.setTrigger(e);
   }
+  /**
+   * Activates a trigger parameter in the animator
+   * @param name The name or hash of the trigger parameter
+   */
   setTrigger(e) {
     var i;
     this._parametersAreDirty = !0, zi && console.log("setTrigger", e), (i = this.runtimeAnimatorController) == null || i.setTrigger(e);
@@ -13505,6 +13943,10 @@ class zt extends I {
   ResetTrigger(e) {
     this.resetTrigger(e);
   }
+  /**
+   * Resets a trigger parameter in the animator
+   * @param name The name or hash of the trigger parameter
+   */
   resetTrigger(e) {
     var i;
     this._parametersAreDirty = !0, zi && console.log("resetTrigger", e), (i = this.runtimeAnimatorController) == null || i.resetTrigger(e);
@@ -13513,6 +13955,11 @@ class zt extends I {
   GetTrigger(e) {
     this.getTrigger(e);
   }
+  /**
+   * Gets the state of a trigger parameter from the animator
+   * @param name The name or hash of the trigger parameter
+   * @returns The state of the trigger parameter
+   */
   getTrigger(e) {
     var s;
     const i = (s = this.runtimeAnimatorController) == null ? void 0 : s.getTrigger(e);
@@ -13522,7 +13969,10 @@ class zt extends I {
   IsInTransition() {
     return this.isInTransition();
   }
-  /** @returns `true` if the animator is currently in a transition */
+  /** 
+   * Checks if the animator is currently in a transition between states
+   * @returns True if the animator is currently blending between animations
+   */
   isInTransition() {
     var e;
     return ((e = this.runtimeAnimatorController) == null ? void 0 : e.isInTransition()) ?? !1;
@@ -13531,15 +13981,26 @@ class zt extends I {
   SetSpeed(e) {
     return this.setSpeed(e);
   }
+  /**
+   * Sets the playback speed of the animator
+   * @param speed The new playback speed multiplier
+   */
   setSpeed(e) {
     var i;
     e !== this._speed && (zi && console.log("setSpeed", e), this._speed = e, ((i = this._animatorController) == null ? void 0 : i.animator) == this && this._animatorController.setSpeed(e));
   }
-  /** Will generate a random speed between the min and max values and set it to the animatorcontroller */
+  /** 
+   * Sets a random playback speed between the min and max values
+   * @param minMax Object with x (minimum) and y (maximum) speed values
+   */
   set minMaxSpeed(e) {
     var i;
     this._speed = $.lerp(e.x, e.y, Math.random()), ((i = this._animatorController) == null ? void 0 : i.animator) == this && this._animatorController.setSpeed(this._speed);
   }
+  /**
+   * Sets a random normalized time offset for animations between min (x) and max (y) values
+   * @param minMax Object with x (min) and y (max) values for the offset range
+   */
   set minMaxOffsetNormalized(e) {
     var i;
     this._normalizedStartOffset = $.lerp(e.x, e.y, Math.random()), ((i = this.runtimeAnimatorController) == null ? void 0 : i.animator) == this && (this.runtimeAnimatorController.normalizedStartOffset = this._normalizedStartOffset);
@@ -14488,10 +14949,15 @@ class In extends I {
   constructor() {
     super(...arguments);
     // public autoOwnership: boolean = true;
+    /** When true, overrides physics behavior when this object is owned by the local user */
     r(this, "overridePhysics", !0);
+    /** Whether to smoothly interpolate position changes when receiving updates */
     r(this, "interpolatePosition", !0);
+    /** Whether to smoothly interpolate rotation changes when receiving updates */
     r(this, "interpolateRotation", !0);
+    /** When true, sends updates at a higher frequency, useful for fast-moving objects */
     r(this, "fastMode", !1);
+    /** When true, notifies other clients when this object is destroyed */
     r(this, "syncDestroy", !1);
     // private _state!: SyncedTransformModel;
     r(this, "_model", null);
@@ -14510,14 +14976,25 @@ class In extends I {
     r(this, "lastWorldPos");
     r(this, "lastWorldRotation");
   }
-  /** Request ownership of an object - you need to be connected to a room */
+  /** 
+   * Requests ownership of this object on the network.
+   * You need to be connected to a room for this to work.
+   */
   requestOwnership() {
     eo && console.log("Request ownership"), this._model ? this._model.requestOwnership() : (this._shouldRequestOwnership = !0, this._needsUpdate = !0);
   }
+  /**
+   * 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
+   */
   hasOwnership() {
     var e;
     return ((e = this._model) == null ? void 0 : e.hasOwnership) ?? void 0;
   }
+  /**
+   * 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
+   */
   isOwned() {
     var e;
     return (e = this._model) == null ? void 0 : e.isOwned;
@@ -14530,10 +15007,17 @@ class In extends I {
   onDestroy() {
     this.syncDestroy && uv(this.guid, this.context.connection), this._model = null, this.context.connection.stopListen(ie.JoinedRoom, this.joinedRoomCallback), this.context.connection.stopListenBinary($c, this.receivedDataCallback);
   }
+  /**
+   * Attempts to retrieve and apply the last known network state for this transform
+   */
   tryGetLastState() {
     const e = this.context.connection.tryGetState(this.guid);
     e && this.onReceivedData(e);
   }
+  /**
+   * Handles incoming network data for this transform
+   * @param data The model containing transform information
+   */
   onReceivedData(e) {
     var i;
     if (!this.destroyed && typeof e.guid == "function" && e.guid() === this.guid) {
@@ -14549,15 +15033,25 @@ class In extends I {
       this._receivedDataBefore = !0;
     }
   }
-  /** @internal */
+  /** 
+   * @internal 
+   * Initializes tracking of position and rotation when component is enabled
+   */
   onEnable() {
     this.lastWorldPos.copy(this.worldPosition), this.lastWorldRotation.copy(this.worldQuaternion), this._needsUpdate = !0, this._model && this._model.updateIsOwned();
   }
-  /** @internal */
+  /** 
+   * @internal 
+   * Releases ownership when component is disabled
+   */
   onDisable() {
     this._model && this._model.freeOwnership();
   }
-  /** @internal */
+  /** 
+   * @internal 
+   * Handles transform synchronization before each render frame
+   * Sends updates when owner, receives and applies updates when not owner
+   */
   onBeforeRender() {
     if (!this.activeAndEnabled || !this.context.connection.isConnected)
       return;
@@ -16313,17 +16807,28 @@ const Jl = (od = class extends I {
     r(this, "_frustum");
     r(this, "_projScreenMatrix", new ne());
   }
+  /**
+   * Returns whether this component is a camera
+   * @returns {boolean} Always returns true
+   */
   get isCamera() {
     return !0;
   }
-  /** The camera's aspect ratio (width divided by height) if it is a perspective camera */
+  /** 
+   * Gets or sets the camera's aspect ratio (width divided by height).
+   * For perspective cameras, this directly affects the camera's projection matrix.
+   * When set, automatically updates the projection matrix.
+   */
   get aspect() {
     return this._cam instanceof ye ? this._cam.aspect : this.context.domWidth / this.context.domHeight;
   }
   set aspect(t) {
     this._cam instanceof ye && this._cam.aspect !== t && (this._cam.aspect = t, this._cam.updateProjectionMatrix());
   }
-  /** The camera's field of view in degrees if it is a perspective camera. Calls updateProjectionMatrix when set */
+  /**
+   * Gets or sets the camera's field of view in degrees for perspective cameras.
+   * When set, automatically updates the projection matrix.
+   */
   get fieldOfView() {
     return this._cam instanceof ye ? this._cam.fov : this._fov;
   }
@@ -16337,7 +16842,11 @@ const Jl = (od = class extends I {
       this._cam.fov = this._fov, this._cam.updateProjectionMatrix();
     }
   }
-  /** The camera's near clipping plane. Calls updateProjectionMatrix when set */
+  /**
+   * Gets or sets the camera's near clipping plane distance.
+   * Objects closer than this distance won't be rendered.
+   * When set, automatically updates the projection matrix.
+   */
   get nearClipPlane() {
     return this._nearClipPlane;
   }
@@ -16345,7 +16854,11 @@ const Jl = (od = class extends I {
     const e = this._nearClipPlane != t;
     this._nearClipPlane = t, this._cam && (e || this._cam.near != t) && (this._cam.near = t, this._cam.updateProjectionMatrix());
   }
-  /** The camera's far clipping plane. Calls updateProjectionMatrix when set */
+  /**
+   * Gets or sets the camera's far clipping plane distance.
+   * Objects farther than this distance won't be rendered.
+   * When set, automatically updates the projection matrix.
+   */
   get farClipPlane() {
     return this._farClipPlane;
   }
@@ -16354,7 +16867,8 @@ const Jl = (od = class extends I {
     this._farClipPlane = t, this._cam && (e || this._cam.far != t) && (this._cam.far = t, this._cam.updateProjectionMatrix());
   }
   /**
-   * Applys both the camera's near and far plane and calls updateProjectionMatrix on the camera.
+   * Applies both the camera's near and far clipping planes and updates the projection matrix.
+   * This ensures rendering occurs only within the specified distance range.
    */
   applyClippingPlane() {
     this._cam && (this._cam.near = this._nearClipPlane, this._cam.far = this._farClipPlane, this._cam.updateProjectionMatrix());
@@ -16371,9 +16885,11 @@ const Jl = (od = class extends I {
   get cullingMask() {
     return this._cam ? this._cam.layers.mask : this._cullingMask;
   }
-  /** Set only a specific layer active to be rendered by the camera.   
-   * This is equivalent to calling `layers.set(val)` 
-   **/
+  /**
+   * Sets only a specific layer to be active for rendering by this camera.
+   * This is equivalent to calling `layers.set(val)` on the three.js camera object.
+   * @param val The layer index to set active
+   */
   set cullingLayer(t) {
     this.cullingMask = (1 << t | 0) >>> 0;
   }
@@ -16423,20 +16939,29 @@ const Jl = (od = class extends I {
     return this._targetTexture;
   }
   /**
-   * Get the three.js camera object. This will create a camera if it does not exist yet.
-   * @returns {PerspectiveCamera | OrthographicCamera} the three camera
-   * @deprecated use {@link threeCamera} instead
+   * Gets the three.js camera object. Creates one if it doesn't exist yet.
+   * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
+   * @deprecated Use {@link threeCamera} instead
    */
   get cam() {
     return this.threeCamera;
   }
   /**
-   * Get the three.js camera object. This will create a camera if it does not exist yet.
-   * @returns {PerspectiveCamera | OrthographicCamera} the three camera
+   * Gets the three.js camera object. Creates one if it doesn't exist yet.
+   * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
    */
   get threeCamera() {
     return this.activeAndEnabled && this.buildCamera(), this._cam;
   }
+  /**
+   * Converts screen coordinates to a ray in world space.
+   * Useful for implementing picking or raycasting from screen to world.
+   * 
+   * @param x The x screen coordinate
+   * @param y The y screen coordinate
+   * @param ray Optional ray object to reuse instead of creating a new one
+   * @returns {Ray} A ray originating from the camera position pointing through the screen point
+   */
   screenPointToRay(t, e, i) {
     const s = this.threeCamera, o = Jl._origin;
     o.set(t, e, -1), this.context.input.convertScreenspaceToRaycastSpace(o), lb && console.log("screenPointToRay", t.toFixed(2), e.toFixed(2), "now:", o.x.toFixed(2), o.y.toFixed(2), "isInXR:" + this.context.isInXR), o.z = -1, o.unproject(s);
@@ -16444,18 +16969,27 @@ const Jl = (od = class extends I {
     return a.sub(l), a.normalize(), i ? (i.set(l, a), i) : new Co(l.clone(), a.clone());
   }
   /**
-   * Get a frustum - it will be created the first time this method is called and updated every frame in onBeforeRender when it exists.  
-   * You can also manually update it using the updateFrustum method.
+   * Gets the camera's view frustum for culling and visibility checks.
+   * Creates the frustum if it doesn't exist and returns it.
+   * 
+   * @returns {Frustum} The camera's view frustum
    */
   getFrustum() {
     return this._frustum || (this._frustum = new z_(), this.updateFrustum()), this._frustum;
   }
-  /** Force frustum update - note that this also happens automatically every frame in onBeforeRender */
+  /**
+   * Forces an update of the camera's frustum.
+   * This is automatically called every frame in onBeforeRender.
+   */
   updateFrustum() {
     this._frustum || (this._frustum = new z_()), this._frustum.setFromProjectionMatrix(this.getProjectionScreenMatrix(this._projScreenMatrix, !0), this.context.renderer.coordinateSystem);
   }
   /**
-   * @returns {Matrix4} this camera's projection screen matrix.
+   * Gets this camera's projection-screen matrix.
+   * 
+   * @param target Matrix4 object to store the result in
+   * @param forceUpdate Whether to force recalculation of the matrix
+   * @returns {Matrix4} The requested projection screen matrix
    */
   getProjectionScreenMatrix(t, e) {
     return e && this._projScreenMatrix.multiplyMatrices(this.threeCamera.projectionMatrix, this.threeCamera.matrixWorldInverse), t === this._projScreenMatrix ? t : t.copy(this._projScreenMatrix);
@@ -16489,8 +17023,9 @@ const Jl = (od = class extends I {
     }
   }
   /** 
-   * Creates a {@link PerspectiveCamera} if it does not exist yet and set the camera's properties. This is internally also called when accessing the {@link cam} property.
-   **/
+   * Creates a three.js camera object if it doesn't exist yet and sets its properties.
+   * This is called internally when accessing the {@link threeCamera} property.
+   */
   buildCamera() {
     if (this._cam)
       return;
@@ -16506,10 +17041,18 @@ const Jl = (od = class extends I {
     }
     this._cam = e, this._cam.layers.mask = this._cullingMask, this.tag == "MainCamera" && this.context.setCurrentCamera(this);
   }
+  /**
+   * Applies clear flags if this is the active main camera.
+   * @param opts Options for applying clear flags
+   */
   applyClearFlagsIfIsActiveCamera(t) {
     this.context.mainCameraComponent === this && this.applyClearFlags(t);
   }
-  /** Apply this camera's clear flags and related settings to the renderer */
+  /**
+   * Applies this camera's clear flags and related settings to the renderer.
+   * This controls how the background is rendered (skybox, solid color, transparent).
+   * @param opts Options for applying clear flags
+   */
   applyClearFlags(t) {
     var e;
     if (!this._cam) {
@@ -16543,14 +17086,17 @@ const Jl = (od = class extends I {
     }
   }
   /**
-   * Apply the skybox to the scene
+   * Applies the skybox texture to the scene background.
    */
   applySceneSkybox() {
     this._skybox || (this._skybox = new sR(this)), this._skybox.apply();
   }
-  /** Used to determine if the background should be transparent when in pass through AR
-   * @returns true when in XR on a pass through device where the background shouldbe invisible 
-   **/
+  /**
+   * Determines if the background should be transparent when in passthrough AR mode.
+   * 
+   * @param context The current rendering context
+   * @returns {boolean} True when in XR on a pass through device where the background should be invisible
+   */
   static backgroundShouldBeTransparent(t) {
     var o, a, l, c;
     const e = (o = t.renderer.xr) == null ? void 0 : o.getSession();
@@ -16620,6 +17166,10 @@ class sR {
     var t;
     return (t = this._camera) == null ? void 0 : t.context;
   }
+  /**
+   * Applies the skybox texture to the scene background.
+   * Retrieves the texture based on the camera's source ID.
+   */
   apply() {
     this._skybox = this.context.lightmaps.tryGetSkybox(this._camera.sourceId), this._skybox ? this.context.scene.background !== this._skybox && (io && console.log(`Camera "${this._camera.name}" set skybox`, this._camera, this._skybox), this._skybox.mapping = Rn, this.context.scene.background = this._skybox) : this._did_log_failed_to_find_skybox || (this._did_log_failed_to_find_skybox = !0, console.warn(`Camera "${this._camera.name}" has no skybox texture. ${this._camera.sourceId}`));
   }
@@ -16636,17 +17186,26 @@ class br extends I {
     });
   }
   /**
-   * Gets the existing or creates a new {@link ThreeAudioListener} instance 
-   * @returns The {@link ThreeAudioListener} instance
+   * Gets the existing Three.js {@link three#AudioListener} instance or creates a new one if it doesn't exist.
+   * This listener is responsible for capturing audio in the 3D scene.
+   * @returns The {@link three#AudioListener} instance
    */
   get listener() {
     return this._listener == null && (this._listener = new Kx()), this._listener;
   }
-  /** @internal */
+  /**
+   * Registers for interaction events and initializes the audio listener
+   * when this component is enabled.
+   * @internal
+   */
   onEnable() {
     $s.registerWaitForInteraction(this.onInteraction), this.addListenerIfItExists();
   }
-  /** @internal */
+  /**
+   * Cleans up event registrations and removes the audio listener
+   * when this component is disabled.
+   * @internal
+   */
   onDisable() {
     $s.unregisterWaitForInteraction(this.onInteraction), this.removeListenerIfItExists();
   }
@@ -16719,31 +17278,48 @@ const It = S("debugaudio"), so = class extends I {
     r(this, "_hasEnded", !0);
     r(this, "_needUpdateSpatialDistanceSettings", !1);
   }
-  /** Check if the user has interacted with the page to allow audio playback.
-   * Internally calling {@link Application.userInteractionRegistered}
+  /**
+   * Checks if the user has interacted with the page to allow audio playback.
+   * Audio playback often requires a user gesture first due to browser autoplay policies.
+   * This is the same as calling {@link Application.userInteractionRegistered}.
+   * 
+   * @returns Whether user interaction has been registered to allow audio playback
    */
   static get userInteractionRegistered() {
     return $s.userInteractionRegistered;
   }
-  /** Register a callback that is called when the user has interacted with the page to allow audio playback.
-   * Internally calling {@link Application.registerWaitForInteraction}
+  /**
+   * Registers a callback that will be executed once the user has interacted with the page,
+   * allowing audio playback to begin.
+   * This is the same as calling {@link Application.registerWaitForInteraction}.
+   * 
+   * @param cb - The callback function to execute when user interaction is registered
    */
   static registerWaitForAllowAudio(t) {
     $s.registerWaitForInteraction(t);
   }
   /**
-   * If true, the audio is currently playing.
+   * Indicates whether the audio is currently playing.
+   * 
+   * @returns True if the audio is playing, false otherwise
    */
   get isPlaying() {
     var t;
     return ((t = this.sound) == null ? void 0 : t.isPlaying) ?? !1;
   }
-  /** The duration of the audio clip in seconds. */
+  /**
+   * The total duration of the current audio clip in seconds.
+   * 
+   * @returns Duration in seconds or undefined if no clip is loaded
+   */
   get duration() {
     var t, e;
     return (e = (t = this.sound) == null ? void 0 : t.buffer) == null ? void 0 : e.duration;
   }
-  /** The current time of the audio clip in 0-1 range. */
+  /**
+   * The current playback position as a normalized value between 0 and 1.
+   * Can be set to seek to a specific position in the audio.
+   */
   get time01() {
     var e;
     const t = this.duration;
@@ -16754,7 +17330,8 @@ const It = S("debugaudio"), so = class extends I {
     e && this.sound && (this.time = t * e);
   }
   /**
-   * The current time of the audio clip in seconds.
+   * The current playback position in seconds.
+   * Can be set to seek to a specific time in the audio.
    */
   get time() {
     var t, e;
@@ -16804,6 +17381,12 @@ const It = S("debugaudio"), so = class extends I {
   get pitch() {
     return this.sound ? this.sound.getPlaybackRate() : 1;
   }
+  /**
+   * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
+   * The audio source needs a user interaction to be initialized due to browser autoplay policies.
+   * 
+   * @returns The three.js PositionalAudio object or null if unavailable
+   */
   get Sound() {
     var t;
     if (!this.sound && so.userInteractionRegistered) {
@@ -16840,10 +17423,20 @@ const It = S("debugaudio"), so = class extends I {
   //         }
   //     }
   // }
+  /**
+   * Indicates whether the audio source is queued to play when possible.
+   * This may be true before user interaction has been registered.
+   * 
+   * @returns Whether the audio source intends to play
+   */
   get ShouldPlay() {
     return this.shouldPlay;
   }
-  /** Get the audio context from the Sound */
+  /**
+   * Returns the Web Audio API context associated with this audio source.
+   * 
+   * @returns The {@link AudioContext} or null if not available
+   */
   get audioContext() {
     var t;
     return (t = this.sound) == null ? void 0 : t.context;
@@ -16897,7 +17490,12 @@ const It = S("debugaudio"), so = class extends I {
     else
       this.shouldPlay = !0, this.createAudio();
   }
-  /** Play a audioclip or mediastream */
+  /**
+   * Plays the audio clip or media stream.
+   * If no argument is provided, plays the currently assigned clip.
+   * 
+   * @param clip - Optional audio clip or {@link MediaStream} to play
+   */
   play(t = void 0) {
     var i, s, o;
     !t && this.clip && (t = this.clip), t !== void 0 && typeof t != "string" && !(t instanceof MediaStream) && (z() && console.warn("Called play on AudioSource with unknown argument type:", t + `
@@ -16913,14 +17511,16 @@ Using the assigned clip instead:`, this.clip), t = this.clip);
     }
   }
   /**
-   * Pause the audio
+   * Pauses audio playback while maintaining the current position.
+   * Use play() to resume from the paused position.
    */
   pause() {
     var t, e;
     It && console.log("Pause", this), this._hasEnded = !0, this.shouldPlay = !1, this.sound && this.sound.isPlaying && this.sound.source && (this._lastContextTime = (t = this.sound) == null ? void 0 : t.context.currentTime, this.sound.pause()), (e = this._audioElement) == null || e.remove();
   }
   /**
-   * Stop the audio and reset the time to 0
+   * Stops audio playback completely and resets the playback position to the beginning.
+   * Unlike pause(), calling play() after stop() will start from the beginning.
    */
   stop() {
     var t, e;
@@ -17976,14 +18576,30 @@ Hg([
 ], sh.prototype, "target", 2);
 const Ll = S("debugavatar");
 class Gg {
+  /**
+   * Creates a new avatar model.
+   * @param root The root object of the avatar
+   * @param head The head object of the avatar
+   * @param leftHand The left hand object of the avatar
+   * @param rigthHand The right hand object of the avatar
+   */
   constructor(t, e, i, s) {
+    /** The root object of the avatar model */
     r(this, "root");
+    /** The head object of the avatar model */
     r(this, "head");
+    /** The left hand object of the avatar model, if available */
     r(this, "leftHand");
+    /** The right hand object of the avatar model, if available */
     r(this, "rigthHand");
     var o;
     this.root = t, this.head = e, this.leftHand = i, this.rigthHand = s, (o = this.root) == null || o.traverse((a) => a.layers.set(2));
   }
+  /**
+   * Checks if the avatar model has a valid configuration.
+   * An avatar is considered valid if it has a head.
+   * @returns Whether the avatar has a valid setup
+   */
   get isValid() {
     return this.head !== null && this.head !== void 0;
   }
@@ -17994,6 +18610,12 @@ class Gv {
   }
   // private loader: GLTFLoader | null;
   // private avatarModelCache: Map<string, AvatarModel | null> = new Map<string, AvatarModel | null>();
+  /**
+   * Retrieves or creates a new avatar instance from an ID or existing Object3D.
+   * @param context The application context
+   * @param avatarId Either a string ID to load an avatar or an existing Object3D to use as avatar
+   * @returns Promise resolving to an AvatarModel if successful, or null if failed
+   */
   async getOrCreateNewAvatarInstance(t, e) {
     if (!e)
       return console.error("Can not create avatar: failed to provide id or root object"), null;
@@ -18010,6 +18632,12 @@ class Gv {
     const s = this.findAvatar(i);
     return s.isValid ? (Ll && console.log("[Custom Avatar] valid config", e, Ll ? s : ""), s) : (console.warn("[Custom Avatar] config isn't valid", e, Ll ? s : ""), null);
   }
+  /**
+   * Loads an avatar model from a file or registry using the provided ID.
+   * @param context The engine context
+   * @param avatarId The ID of the avatar to load
+   * @returns Promise resolving to the loaded avatar's Object3D, or null if failed
+   */
   async loadAvatar(t, e) {
     if (console.assert(e != null && typeof e == "string", "Avatar id must not be null"), e.length <= 0 || !e)
       return null;
@@ -18042,9 +18670,18 @@ class Gv {
       );
     });
   }
+  /**
+   * Caches an avatar model for reuse.
+   * @param _id The ID to associate with the model
+   * @param _model The avatar model to cache
+   */
   cacheModel(t, e) {
   }
-  // TODO this should be burned to the ground once 🤞 we have proper extras that define object relations.
+  /**
+   * Analyzes an Object3D to find avatar parts (head, hands) based on naming conventions.
+   * @param obj The Object3D to search for avatar parts
+   * @returns A structured AvatarModel with references to found parts
+   */
   findAvatar(t) {
     const e = t;
     let i = e;
@@ -18060,6 +18697,12 @@ class Gv {
     }
     return new Gg(e, s, o, a);
   }
+  /**
+   * Recursively searches for an avatar part by name within an Object3D hierarchy.
+   * @param obj The Object3D to search within
+   * @param searchString Array of strings that should all be present in the object name
+   * @returns The found Object3D part or null if not found
+   */
   findAvatarPart(t, e) {
     const i = t.name.toLowerCase();
     let s = !0;
@@ -18078,6 +18721,12 @@ class Gv {
       }
     return null;
   }
+  /**
+   * Handles HTTP response errors from avatar loading operations.
+   * @param response The fetch API response to check
+   * @returns The response if it was ok
+   * @throws Error with status text if response was not ok
+   */
   handleCustomAvatarErrors(t) {
     if (!t.ok)
       throw Error(t.statusText);
@@ -18097,6 +18746,10 @@ class nh extends I {
     r(this, "isGizmo", !1);
     r(this, "_axes", null);
   }
+  /**
+   * Creates and adds the axes visualization to the scene when the component is enabled.
+   * If marked as a gizmo, it will only be shown when gizmos are enabled in the global parameters.
+   */
   onEnable() {
     if (this.isGizmo && !Yc)
       return;
@@ -18104,6 +18757,9 @@ class nh extends I {
     const e = this._axes.material;
     e && e.depthTest !== void 0 && (e.depthTest = this.depthTest);
   }
+  /**
+   * Removes the axes visualization from the scene when the component is disabled.
+   */
   onDisable() {
     this._axes && this.gameObject.remove(this._axes);
   }
@@ -18147,11 +18803,17 @@ class qv extends I {
 const IR = S("gizmos"), DR = S("debugboxhelper"), ps = class extends I {
   constructor() {
     super(...arguments);
+    /** The bounding box for this component */
     r(this, "box", null);
     r(this, "_lastMatrixUpdateFrame", -1);
     r(this, "_helper", null);
     r(this, "_color", null);
   }
+  /**
+   * Tests if an object intersects with this helper's bounding box
+   * @param obj The object to test for intersection
+   * @returns True if objects intersect, false if not, undefined if the provided object is invalid
+   */
   isInBox(e) {
     var s;
     if (!e)
@@ -18164,9 +18826,19 @@ const IR = S("gizmos"), DR = S("debugboxhelper"), ps = class extends I {
     const i = (s = this.box) == null ? void 0 : s.intersectsBox(ps.testBox);
     return i && DR && V.DrawWireBox3(ps.testBox, 16711680, 5), i;
   }
+  /**
+   * Tests if this helper's bounding box intersects with another box
+   * @param box The {@link Box3} to test for intersection
+   * @returns True if boxes intersect, false otherwise
+   */
   intersects(e) {
     return e ? this.updateBox(!1).intersectsBox(e) : !1;
   }
+  /**
+   * Updates the helper's bounding box based on the gameObject's position and scale
+   * @param force Whether to force an update regardless of frame count
+   * @returns The updated {@link Box3}
+   */
   updateBox(e = !1) {
     if (this.box || (this.box = new Mi()), e || this.context.time.frameCount != this._lastMatrixUpdateFrame) {
       const i = this._lastMatrixUpdateFrame < 0;
@@ -18179,6 +18851,11 @@ const IR = S("gizmos"), DR = S("debugboxhelper"), ps = class extends I {
   awake() {
     this._helper = null, this._color = null, this.box = null;
   }
+  /**
+   * Creates and displays a visual wireframe representation of this box helper
+   * @param col Optional color for the wireframe. If not provided, uses default color
+   * @param force If true, shows the helper even if gizmos are disabled
+   */
   showHelper(e = null, i = !1) {
     var s;
     if (!(!IR && !i)) {
@@ -18206,14 +18883,18 @@ class Ei extends I {
     r(this, "membership", [0]);
     r(this, "filter");
     /**
-     * Apply the collider properties to the physics engine.
+     * Updates the collider's properties in the physics engine.
+     * Use this when you've changed collider properties and need to sync with the physics engine.
      */
     r(this, "updateProperties", () => {
       var e;
       (e = this.context.physics.engine) == null || e.updateProperties(this);
     });
   }
-  /** @internal */
+  /**
+   * Identifies this component as a collider.
+   * @internal
+   */
   get isCollider() {
     return !0;
   }
@@ -18234,12 +18915,18 @@ class Ei extends I {
     var e;
     (e = this.context.physics.engine) == null || e.removeBody(this);
   }
-  /** Returns the underlying physics body from the physics engine (if any) - the component must be enabled and active in the scene */
+  /**
+   * Returns the underlying physics body from the physics engine.
+   * Only available if the component is enabled and active in the scene.
+   */
   get body() {
     var e;
     return (e = this.context.physics.engine) == null ? void 0 : e.getBody(this);
   }
-  /** Requests an update of the physics material in the physics engine */
+  /**
+   * Updates the physics material in the physics engine.
+   * Call this after changing the sharedMaterial property.
+   */
   updatePhysicsMaterial() {
     var e;
     (e = this.context.physics.engine) == null || e.updatePhysicsMaterial(this);
@@ -18266,13 +18953,22 @@ class oh extends Ei {
     r(this, "radius", 0.5);
     r(this, "center", new v(0, 0, 0));
   }
+  /**
+   * Registers the sphere collider with the physics engine and sets up scale change monitoring.
+   */
   onEnable() {
     var e;
     super.onEnable(), (e = this.context.physics.engine) == null || e.addSphereCollider(this), mg(this.gameObject.scale, this.updateProperties);
   }
+  /**
+   * Removes scale change monitoring when the collider is disabled.
+   */
   onDisable() {
     super.onDisable(), P0(this.gameObject.scale, this.updateProperties);
   }
+  /**
+   * Updates collider properties when validated in the editor or inspector.
+   */
   onValidate() {
     this.updateProperties();
   }
@@ -18290,23 +18986,43 @@ const Xv = class extends Ei {
     r(this, "size", new v(1, 1, 1));
     r(this, "center", new v(0, 0, 0));
   }
+  /**
+   * Creates and adds a BoxCollider to the given object.
+   * @param obj The object to add the collider to
+   * @param opts Configuration options for the collider and optional rigidbody
+   * @returns The newly created BoxCollider
+   */
   static add(t, e) {
     const i = Ji(t, Xv);
     return i.autoFit(), (e == null ? void 0 : e.rigidbody) === !0 && Ji(t, _e, { isKinematic: !1 }), i;
   }
-  /** @internal */
+  /**
+   * Registers the box collider with the physics engine and sets up scale change monitoring.
+   * @internal
+   */
   onEnable() {
     var t;
     super.onEnable(), (t = this.context.physics.engine) == null || t.addBoxCollider(this, this.size), mg(this.gameObject.scale, this.updateProperties);
   }
-  /** @internal */
+  /**
+   * Removes scale change monitoring when the collider is disabled.
+   * @internal
+   */
   onDisable() {
     super.onDisable(), P0(this.gameObject.scale, this.updateProperties);
   }
-  /** @internal */
+  /**
+   * Updates collider properties when validated in the editor or inspector.
+   * @internal
+   */
   onValidate() {
     this.updateProperties();
   }
+  /**
+   * Automatically fits the collider to the geometry of the object.
+   * Sets the size and center based on the object's bounding box.
+   * @param opts Options object with a debug flag to visualize the bounding box
+   */
   autoFit(t) {
     const e = this.gameObject, i = e.position.clone(), s = e.quaternion.clone(), o = e.scale.clone(), a = e.parent;
     e.position.set(0, 0, 0), e.quaternion.set(0, 0, 0, 1), e.scale.set(1, 1, 1), e.parent = null, e.updateMatrix();
@@ -18328,6 +19044,10 @@ class Fr extends Ei {
     r(this, "sharedMesh");
     r(this, "convex", !1);
   }
+  /**
+   * Creates and registers the mesh collider with the physics engine.
+   * Handles both individual meshes and mesh groups.
+   */
   onEnable() {
     var i, s, o;
     if (super.onEnable(), !this.context.physics.engine)
@@ -18357,7 +19077,7 @@ class Fr extends Ei {
             p && this.activeAndEnabled && (h.geometry = p, (u = this.context.physics.engine) == null || u.addMeshCollider(this, h, this.convex));
         });
       } else
-        console.warn("A MeshCollider mesh is assigned, but it's neither a Mesh nor a Group. Please report a bug!", this, this.sharedMesh);
+        (z() || S("showcolliders")) && console.warn(`[MeshCollider] A MeshCollider mesh is assigned to an unknown object on "${this.gameObject.name}", but it's neither a Mesh nor a Group. Please double check that you attached the collider component to the right object and report a bug otherwise!`, this);
     }
   }
 }
@@ -18374,6 +19094,9 @@ class Mo extends Ei {
     r(this, "radius", 0.5);
     r(this, "height", 2);
   }
+  /**
+   * Registers the capsule collider with the physics engine.
+   */
   onEnable() {
     var e;
     super.onEnable(), (e = this.context.physics.engine) == null || e.addCapsuleCollider(this, this.height, this.radius);
@@ -18828,24 +19551,33 @@ const Ui = (Hl = class extends I {
     r(this, "_didDrag", !1);
   }
   /**
+   * Checks if any DragControls component is currently active with selected objects
    * @returns True if any DragControls component is currently active
    */
   static get HasAnySelected() {
     return this._active > 0;
   }
-  /** @returns a list of DragControl components that are currently active */
+  /** 
+   * Retrieves a list of all DragControl components that are currently dragging objects.
+   * @returns Array of currently active DragControls components
+   */
   static get CurrentlySelected() {
     rp.length = 0;
     for (const t of this._instances)
       t._isDragging && rp.push(t);
     return rp;
   }
-  /** The currently dragged object (if any) */
+  /** 
+   * Returns the object currently being dragged by this DragControls component, if any.
+   * @returns The object being dragged or null if no object is currently dragged
+   */
   get draggedObject() {
     return this._targetObject;
   }
   /**
-   * Use to update the object that is being dragged by the DragControls
+   * Updates the object that is being dragged by the DragControls.
+   * This can be used to change the target during a drag operation.
+   * @param obj The new object to drag, or null to stop dragging
    */
   setTargetObject(t) {
     var i, s;
@@ -18871,25 +19603,46 @@ const Ui = (Hl = class extends I {
   onDisable() {
     Ui._instances = Ui._instances.filter((t) => t !== this);
   }
+  /**
+   * Checks if editing is allowed for the current networking connection.
+   * @param _obj Optional object to check edit permissions for
+   * @returns True if editing is allowed
+   */
   allowEdit(t = null) {
     return this.context.connection.allowEditing;
   }
-  /** @internal */
+  /** 
+   * Handles pointer enter events. Sets the cursor style and tracks the hovered object.
+   * @param evt Pointer event data containing information about the interaction
+   * @internal
+   */
   onPointerEnter(t) {
     if (!this.allowEdit(this.gameObject) || t.mode !== "screen" || (t.event.mode === "tracked-pointer" || t.event.mode === "transient-pointer" ? this.xrDragMode : this.dragMode) === 5)
       return;
     const s = C.getComponentInParent(t.object, Ui);
     !s || s !== this || (Ui.lastHovered = t.object, this.context.domElement.style.cursor = "pointer");
   }
-  /** @internal */
+  /** 
+   * Handles pointer movement events. Marks the event as used if dragging is active.
+   * @param args Pointer event data containing information about the movement
+   * @internal
+   */
   onPointerMove(t) {
     (this._isDragging || this._potentialDragStartEvt !== null) && t.use();
   }
-  /** @internal */
+  /** 
+   * Handles pointer exit events. Resets the cursor style when the pointer leaves a draggable object.
+   * @param evt Pointer event data containing information about the interaction
+   * @internal
+   */
   onPointerExit(t) {
     this.allowEdit(this.gameObject) && t.mode === "screen" && Ui.lastHovered === t.object && (this.context.domElement.style.cursor = "auto");
   }
-  /** @internal */
+  /** 
+   * Handles pointer down events. Initiates the potential drag operation if conditions are met.
+   * @param args Pointer event data containing information about the interaction
+   * @internal
+   */
   onPointerDown(t) {
     if (!(!this.allowEdit(this.gameObject) || t.used || (t.mode === "tracked-pointer" || t.mode === "transient-pointer" ? this.xrDragMode : this.dragMode) === 5) && (Ui.lastHovered = t.object, t.button === 0)) {
       this._dragHandlers.size === 0 && (this._didDrag = !1, this._totalMovement.set(0, 0, 0), this._potentialDragStartEvt = t), this._targetObject || this.setTargetObject(this.gameObject), Ui._active += 1;
@@ -18905,7 +19658,11 @@ const Ui = (Hl = class extends I {
       t.use();
     }
   }
-  /** @internal */
+  /** 
+   * Handles pointer up events. Finalizes or cancels the drag operation.
+   * @param args Pointer event data containing information about the interaction
+   * @internal
+   */
   onPointerUp(t) {
     if (zs && V.DrawLabel(t.point ?? this.gameObject.worldPosition, "POINTERUP:" + t.pointerId + ", " + t.button, 0.03, 3), !this.allowEdit(this.gameObject) || t.button !== 0)
       return;
@@ -18913,7 +19670,11 @@ const Ui = (Hl = class extends I {
     const e = this._dragHandlers.get(t.event.space), i = this._dragHandlers.get(this.gameObject);
     i && (i.handlerA === e || i.handlerB === e) && (this._dragHandlers.delete(this.gameObject), i.onDragEnd(t)), e && (Ui._active > 0 && (Ui._active -= 1), this.setTargetObject(null), e.onDragEnd && e.onDragEnd(t), this._dragHandlers.delete(t.event.space), this._dragHandlers.size === 0 && this.onLastDragEnd(t), t.use());
   }
-  /** @internal */
+  /**
+   * Updates the drag operation every frame. Processes pointer movement, accumulates drag distance
+   * and triggers drag start once there's enough movement.
+   * @internal
+   */
   update() {
     for (const t of this._dragHandlers.values())
       t.collectMovementInfo && t.collectMovementInfo(), t.getTotalMovement && this._totalMovement.add(t.getTotalMovement());
@@ -18930,7 +19691,12 @@ const Ui = (Hl = class extends I {
       t.onDragUpdate && t.onDragUpdate(this._dragHandlers.size);
     this._dragHelper && this._dragHelper.hasSelected && this.onAnyDragUpdate();
   }
-  /** Called when the first pointer starts dragging on this object. Not called for subsequent pointers on the same object. */
+  /** 
+   * Called when the first pointer starts dragging on this object. 
+   * Sets up network synchronization and marks rigidbodies for dragging.
+   * Not called for subsequent pointers on the same object.
+   * @param evt Pointer event data that initiated the drag
+   */
   onFirstDragStart(t) {
     if (!t || !t.object)
       return;
@@ -18946,7 +19712,10 @@ const Ui = (Hl = class extends I {
     const o = C.getComponentsInChildren(i, _e);
     o && this._draggingRigidbodies.push(...o);
   }
-  /** Called each frame as long as any pointer is dragging this object. */
+  /** 
+   * Called each frame as long as any pointer is dragging this object.
+   * Updates visuals and keeps rigidbodies awake during the drag.
+   */
   onAnyDragUpdate() {
     if (!this._dragHelper)
       return;
@@ -18956,7 +19725,11 @@ const Ui = (Hl = class extends I {
     const t = this._targetObject || this.gameObject;
     _s.markDirty(t);
   }
-  /** Called when the last pointer has been removed from this object. */
+  /** 
+   * Called when the last pointer has been removed from this object.
+   * Cleans up drag state and applies final velocities to rigidbodies.
+   * @param evt Pointer event data for the last pointer that was lifted
+   */
   onLastDragEnd(t) {
     if (!this || !this._isDragging)
       return;
@@ -18972,7 +19745,7 @@ const Ui = (Hl = class extends I {
     const e = this._dragHelper.selected;
     zs && console.log("DRAG END", e, e == null ? void 0 : e.visible), this._dragHelper.setSelected(null, this.context);
   }
-}, r(Hl, "_active", 0), /** Currently active and enabled DragControls components */
+}, r(Hl, "_active", 0), /** Registry of currently active and enabled DragControls components */
 r(Hl, "_instances", []), r(Hl, "lastHovered"), Hl);
 let Oi = Ui;
 zr([
@@ -19121,14 +19894,22 @@ class ap {
     r(this, "_lastSurfaceHitPoint", new v());
     this.settings = t, this.context = t.context, this.gameObject = e, this._followObject = new D();
   }
-  /** Absolute movement of the pointer. Used for determining if a motion/drag is happening. 
-   * This is in world units, so very small for screens (near-plane space change) */
+  /** 
+   * Returns the accumulated movement of the pointer in world units.
+   * Used for determining if enough motion has occurred to start a drag.
+   */
   getTotalMovement() {
     return this._totalMovement;
   }
+  /** 
+   * Returns the object that follows the pointer during dragging operations.
+   */
   get followObject() {
     return this._followObject;
   }
+  /**
+   * Returns the point where the pointer initially hit the object in local space.
+   */
   get hitPointInLocalSpace() {
     return this._hitPointInLocalSpace;
   }
@@ -19309,7 +20090,9 @@ class ap {
 }
 const D_ = class {
   constructor(t) {
+    /** Controls whether visual helpers like lines and markers are displayed */
     r(this, "showGizmo", !0);
+    /** When true, drag plane alignment changes based on view angle */
     r(this, "useViewAngle", !0);
     r(this, "_selected", null);
     r(this, "_context", null);
@@ -19338,9 +20121,15 @@ const D_ = class {
     const s = new wu(0.5, 22, 22), o = new Te({ color: i.color }), a = new q(s, o);
     a.visible = !1, a.layers.set(2), this._groundMarker = a;
   }
+  /**
+   * Checks if there is a currently selected object being visualized
+   */
   get hasSelected() {
     return this._selected !== null && this._selected !== void 0;
   }
+  /**
+   * Returns the currently selected object being visualized, if any
+   */
   get selected() {
     return this._selected;
   }
@@ -19473,6 +20262,10 @@ var QR = Object.defineProperty, YR = Object.getOwnPropertyDescriptor, ll = (n, t
 };
 const gs = S("debugdroplistener");
 class KR extends CustomEvent {
+  /**
+   * Creates a new added event with the provided details
+   * @param detail Information about the added object
+   */
   constructor(t) {
     super("object-added", { detail: t });
   }
@@ -19487,6 +20280,10 @@ class Io extends I {
     r(this, "fitVolumeSize", new v(1, 1, 1));
     r(this, "placeAtHitPosition", !0);
     r(this, "onDropped", new be());
+    /**
+     * Handles network events received from other clients containing information about dropped objects
+     * @param evt Network event data containing object information, position, and content URL
+     */
     r(this, "onNetworkEvent", (e) => {
       var i;
       if (!this.useNetworking) {
@@ -19503,6 +20300,11 @@ class Io extends I {
             this.addFromUrl(s, { screenposition: new oe(), point: e.point, size: e.size }, !0);
       }
     });
+    /**
+     * Handles clipboard paste events and processes them as potential URL drops
+     * Only URLs are processed by this handler, and only when editing is allowed
+     * @param evt The paste event
+     */
     r(this, "handlePaste", (e) => {
       if (this.context.connection.allowEditing === !1 || e.defaultPrevented)
         return;
@@ -19513,9 +20315,19 @@ class Io extends I {
         }
       }).catch(console.warn);
     });
+    /**
+     * Handles drag events over the renderer's canvas
+     * Prevents default behavior to enable drop events
+     * @param evt The drag event
+     */
     r(this, "onDrag", (e) => {
       this.context.connection.allowEditing !== !1 && e.preventDefault();
     });
+    /**
+     * Processes drop events to add files to the scene
+     * Handles both file drops and text/URL drops
+     * @param evt The drop event
+     */
     r(this, "onDrop", async (e) => {
       if (this.context.connection.allowEditing === !1 || (gs && console.log(e), !(e != null && e.dataTransfer)) || e["droplistener:handled"])
         return;
@@ -19568,6 +20380,14 @@ class Io extends I {
   forgetObjects() {
     this.removePreviouslyAddedObjects(!1);
   }
+  /**
+   * Processes a dropped or pasted URL and tries to load it as a 3D model
+   * Handles special cases like GitHub URLs and Polyhaven asset URLs
+   * @param url The URL to process
+   * @param ctx Context information about where the drop occurred
+   * @param isRemote Whether this URL was shared from a remote client
+   * @returns The added object or null if loading failed
+   */
   async addFromUrl(e, i, s) {
     gs && console.log("dropped url", e);
     try {
@@ -19596,6 +20416,12 @@ class Io extends I {
     }
     return null;
   }
+  /**
+   * Processes dropped files, loads them as 3D models, and handles networking if enabled
+   * Creates an abort controller to cancel previous uploads if new files are dropped
+   * @param fileList Array of dropped files
+   * @param ctx Context information about where the drop occurred
+   */
   async addDroppedFiles(e, i) {
     var s, o;
     if (gs && console.log("Add files", e), !!Array.isArray(e) && e.length) {
@@ -19616,7 +20442,10 @@ class Io extends I {
       }
     }
   }
-  /** Removes all previously added objects from the scene and removes those object references  */
+  /**
+   * Removes all previously added objects from the scene
+   * @param doDestroy When true, destroys the objects; when false, just clears the references
+   */
   removePreviouslyAddedObjects(e = !0) {
     if (e)
       for (const i of this._addedObjects)
@@ -19624,7 +20453,13 @@ class Io extends I {
     this._addedObjects.length = 0, this._addedModels.length = 0;
   }
   /**
-   * Adds the object to the scene and fits it into the volume if {@link fitIntoVolume} is enabled.
+   * Adds a loaded model to the scene with proper positioning and scaling.
+   * Handles placement based on component settings and raycasting.
+   * If {@link fitIntoVolume} is enabled, the object will be scaled to fit within the volume defined by {@link fitVolumeSize}.
+   * @param data The loaded model data and content hash
+   * @param ctx Context information about where the drop occurred
+   * @param isRemote Whether this object was shared from a remote client
+   * @returns The added object or null if adding failed
    */
   addObject(e, i, s) {
     var d, u;
@@ -19660,6 +20495,13 @@ class Io extends I {
     });
     return this.dispatchEvent(h), (d = this.onDropped) == null || d.invoke(h.detail), !s && ((u = i.url) != null && u.startsWith("http")) && this.context.connection.isConnected && l && this.sendDropEvent(i.url, l, a), l;
   }
+  /**
+   * Sends a network event to other clients about a dropped object
+   * Only triggered when networking is enabled and the connection is established
+   * @param url The URL to the content that was dropped
+   * @param obj The object that was added to the scene
+   * @param contentmd5 The content hash for verification
+   */
   async sendDropEvent(e, i, s) {
     if (!this.useNetworking) {
       gs && console.debug("[DropListener] Ignoring networked event because networking is disabled", e);
@@ -19678,9 +20520,18 @@ class Io extends I {
       this.context.connection.send("droplistener", a);
     }
   }
+  /**
+   * Deletes remote state for this DropListener's objects
+   * Called when new files are dropped to clean up previous state
+   */
   deleteDropEvent() {
     this.context.connection.sendDeleteRemoteState(this.guid);
   }
+  /**
+   * Tests if a drop event occurred within the designated drop area if one is specified
+   * @param ctx The drop context containing screen position information
+   * @returns True if the drop is valid (either no drop area is set or the drop occurred inside it)
+   */
   testIfIsInDropArea(e) {
     if (this.dropArea) {
       const i = this.context.input.convertScreenspaceToRaycastSpace(e.screenposition.clone());
@@ -27405,6 +28256,9 @@ const Kt = S("debugplayersync"), $w = class extends I {
     r(this, "onJoinedRoom", () => {
       Kt && console.log("PlayerSync.joinedRoom. autoSync is set to " + this.autoSync), this.autoSync && this.getInstance();
     });
+    /**
+     * Destroys the current player instance and cleans up networking state
+     */
     r(this, "destroyInstance", () => {
       var t;
       (t = this._localInstance) == null || t.then((e) => {
@@ -27414,7 +28268,10 @@ const Kt = S("debugplayersync"), $w = class extends I {
   }
   /**
    * This API is experimental and may change or be removed in the future.
-   * Create a PlayerSync instance at runtime from a given URL
+   * Creates a PlayerSync instance at runtime from a given URL and sets it up for networking
+   * @param url Path to the asset that should be instantiated for each player
+   * @param init Optional initialization parameters for the PlayerSync component
+   * @returns Promise resolving to a PlayerSync instance with a guaranteed asset property
    * @example
    * ```typescript
    * const res = await PlayerSync.setupFrom("/assets/demo.glb");
@@ -27443,6 +28300,10 @@ const Kt = S("debugplayersync"), $w = class extends I {
   onDisable() {
     this.context.connection.stopListen(ie.RoomStateSent, this.onJoinedRoom), this.context.connection.stopListen(ie.JoinedRoom, this.onJoinedRoom), this.context.connection.stopListen(ie.LeftRoom, this.destroyInstance);
   }
+  /**
+   * Gets or creates an instance of the assigned asset for the local player
+   * @returns Promise resolving to the instantiated player object or null if creation failed
+   */
   async getInstance() {
     var e, i, s, o, a, l;
     if (this._localInstance)
@@ -27463,6 +28324,9 @@ const Kt = S("debugplayersync"), $w = class extends I {
       this._localInstance = void 0, console.warn("PlayerSync: failed instantiating asset!");
     return this._localInstance;
   }
+  /**
+   * Sets up visibility change listeners to handle player cleanup when browser tab visibility changes
+   */
   watchTabVisible() {
     window.addEventListener("visibilitychange", (t) => {
       if (document.visibilityState === "visible")
@@ -27487,12 +28351,21 @@ var AT = /* @__PURE__ */ ((n) => (n.OwnerChanged = "ownerChanged", n))(AT || {})
 const Mt = (Gl = class extends I {
   constructor() {
     super(...arguments);
+    /** Event triggered when the owner of this PlayerState changes */
     r(this, "onOwnerChangeEvent", new be());
+    /** Event triggered the first time an owner is assigned to this PlayerState */
     r(this, "onFirstOwnerChangeEvent", new be());
+    /** Indicates if this PlayerState has an owner assigned */
     r(this, "hasOwner", !1);
     r(this, "owner");
-    /** when enabled PlayerSync will not destroy itself when not connected anymore */
+    /** 
+     * When enabled, PlayerState will not destroy itself when the owner is not connected anymore 
+     */
     r(this, "dontDestroy", !1);
+    /**
+     * Handler for when a user leaves the networked room
+     * @param model Object containing the ID of the user who left
+     */
     r(this, "onUserLeftRoom", (t) => {
       if (t.userId === this.owner) {
         Kt && console.log("PLAYERSYNC LEFT", this.owner), this.doDestroy();
@@ -27500,31 +28373,48 @@ const Mt = (Gl = class extends I {
       }
     });
   }
-  /** all instances for all players */
+  /** All PlayerState instances for all players in the scene */
   static get all() {
     return Mt._all;
   }
-  /** all instances for the local player */
+  /** All PlayerState instances that belong to the local player */
   static get local() {
     return Mt._local;
   }
+  /**
+   * Gets the PlayerState component for a given object or component
+   * @param obj Object3D or Component to find the PlayerState for
+   * @returns The PlayerState component if found, undefined otherwise
+   */
   static getFor(t) {
     if (t instanceof D)
       return C.getComponentInParent(t, Mt);
     if (t instanceof I)
       return C.getComponentInParent(t.gameObject, Mt);
   }
-  //** use to check if a component or gameobject is part of a instance owned by the local player */
+  /**
+   * Checks if a given object or component belongs to the local player
+   * @param obj Object3D or Component to check
+   * @returns True if the object belongs to the local player, false otherwise
+   */
   static isLocalPlayer(t) {
     const e = Mt.getFor(t);
     return (e == null ? void 0 : e.isLocalPlayer) ?? !1;
   }
   /**
-   * Add a callback for a PlayerStateEvent
+   * Registers a callback for a specific PlayerState event
+   * @param event The event to listen for
+   * @param cb Callback function that will be invoked when the event occurs
+   * @returns The provided callback function for chaining
    */
   static addEventListener(t, e) {
     return this._callbacks[t] || (this._callbacks[t] = []), this._callbacks[t].push(e), e;
   }
+  /**
+   * Removes a previously registered event callback
+   * @param event The event type to remove the callback from
+   * @param cb The callback function to remove
+   */
   static removeEventListener(t, e) {
     if (!this._callbacks[t])
       return;
@@ -27536,9 +28426,17 @@ const Mt = (Gl = class extends I {
       for (const i of this._callbacks[t])
         i(e);
   }
+  /**
+   * Indicates if this PlayerState belongs to the local player
+   */
   get isLocalPlayer() {
     return this.owner === this.context.connection.connectionId;
   }
+  /**
+   * Handles owner change events and updates relevant state
+   * @param newOwner The new owner's connection ID
+   * @param oldOwner The previous owner's connection ID
+   */
   onOwnerChange(t, e) {
     var a, l;
     Kt && console.log(`PlayerSync.onOwnerChange: ${e} → ${t} (me: ${this.context.connection.connectionId})`);
@@ -27567,7 +28465,7 @@ const Mt = (Gl = class extends I {
       !this.destroyed && !this.owner ? this.dontDestroy ? Kt && console.warn("PlayerState.start → owner is still undefined but dontDestroy is set to true", this.name) : (Kt && console.warn(`PlayerState.start → owner is still undefined: destroying "${this.name}" instance now`), this.doDestroy()) : Kt && console.log("PlayerState.start → owner is assigned", this.owner);
     }, 2e3));
   }
-  /** this tells the server that this client has been destroyed and the networking message for the instantiate will be removed */
+  /** Tells the server that this client has been destroyed, and the networking message for the instantiate will be removed      */
   doDestroy() {
     Kt && console.log("PlayerSync.doDestroy → syncDestroy", this.name), ju(this.gameObject, this.context.connection, !0, { saveInRoom: !1 });
   }
@@ -27578,8 +28476,7 @@ const Mt = (Gl = class extends I {
       t >= 0 && Mt._local.splice(t, 1);
     }
   }
-}, r(Gl, "_all", []), r(Gl, "_local", []), // static Callback
-r(Gl, "_callbacks", {}), Gl);
+}, r(Gl, "_all", []), r(Gl, "_local", []), r(Gl, "_callbacks", {}), Gl);
 let Zi = Mt;
 sf([
   Nw(Zi.prototype.onOwnerChange)
@@ -27599,11 +28496,16 @@ class $n extends I {
     r(this, "createMuteButton");
     r(this, "createQRCodeButton");
   }
-  /** @hidden */
+  /** 
+   * Applies the configured menu options when the component is enabled
+   * @hidden
+   */
   onEnable() {
     this.applyOptions();
   }
-  /** applies the options to `this.context.menu` */
+  /** 
+   * Applies all configured options to the active {@link Context.menu}.
+   */
   applyOptions() {
     this.context.menu.setPosition(this.position), this.context.menu.showNeedleLogo(this.showNeedleLogo), this.createFullscreenButton === !0 && this.context.menu.showFullscreenOption(!0), this.createMuteButton === !0 && this.context.menu.showAudioPlaybackOption(!0), this.showSpatialMenu === !0 && this.context.menu.showSpatialMenu(this.showSpatialMenu), this.createQRCodeButton === !0 && (X.isMobileDevice() || this.context.menu.showQRCodeButton(!0));
   }
@@ -28203,7 +29105,7 @@ const va = (Hp = class extends I {
     r(this, "usePlacementAdjustment", !0);
     r(this, "arScale", 1);
     r(this, "useXRAnchor", !1);
-    r(this, "autoPlace", !0);
+    r(this, "autoPlace", !1);
     r(this, "autoCenter", !1);
     r(this, "useQuicklookExport", !1);
     r(this, "useDepthSensing", !1);
@@ -28216,23 +29118,50 @@ const va = (Hp = class extends I {
     r(this, "_exitXRMenuButton");
     r(this, "_previousXRState", 0);
     r(this, "_spatialGrabRaycaster");
+    /**
+     * Event handler called when a player avatar is spawned.
+     * Ensures the avatar has the necessary Avatar component.
+     * @param instance The spawned avatar 3D object
+     */
     r(this, "onAvatarSpawned", (t) => {
       zl && console.log("WebXR.onAvatarSpawned", t), C.getComponentInChildren(t, Rr) ?? (e = C.addComponent(t, Rr));
     });
+    /**
+     * Reference to the WebXR button factory used by this component.
+     */
     r(this, "_buttonFactory");
+    /**
+     * Storage for UI buttons created by this component.
+     */
     r(this, "_buttons", []);
   }
+  /**
+   * Initializes the WebXR component by obtaining the XR sync object for this context.
+   */
   awake() {
     J.getXRSync(this.context);
   }
+  /**
+   * Sets up the WebXR component when it's enabled. Checks for HTTPS connection,
+   * sets up USDZ export if enabled, creates UI buttons, and configures avatar settings.
+   */
   onEnable() {
     var t, e;
     window.location.protocol !== "https:" && we('<a href="https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API" target="_blank">WebXR</a> only works on secure connections (https).'), this.useQuicklookExport && (C.findObjectOfType(qe) || (zl && console.log("WebXR: Adding USDZExporter"), this._usdzExporter = C.addComponent(this.gameObject, qe), this._usdzExporter.objectToExport = this.context.scene, this._usdzExporter.autoExportAnimations = !0, this._usdzExporter.autoExportAudioSources = !0)), this.handleCreatingHTML(), this.handleOfferSession(), this.defaultAvatar === !0 && (zl && console.warn("WebXR: No default avatar set, using static default avatar"), this.defaultAvatar = new re("https://cdn.needle.tools/static/avatars/DefaultAvatar.glb")), this.defaultAvatar && (this._playerSync = this.gameObject.getOrAddComponent(ph), this._playerSync.autoSync = !1), this._playerSync && typeof this.defaultAvatar != "boolean" && (this._playerSync.asset = this.defaultAvatar, (t = this._playerSync.onPlayerSpawned) == null || t.removeEventListener(this.onAvatarSpawned), (e = this._playerSync.onPlayerSpawned) == null || e.addEventListener(this.onAvatarSpawned));
   }
+  /**
+   * Cleans up resources when the component is disabled.
+   * Destroys the USDZ exporter if one was created and removes UI buttons.
+   */
   onDisable() {
     var t;
     (t = this._usdzExporter) == null || t.destroy(), this.removeButtons();
   }
+  /**
+   * Checks if WebXR is supported and offers an appropriate session.
+   * This is used to show the WebXR session joining prompt in browsers that support it.
+   * @returns A Promise that resolves to true if a session was offered, false otherwise
+   */
   async handleOfferSession() {
     return this.createVRButton && await J.isVRSupported() && this.createVRButton ? J.offerSession("immersive-vr", "default", this.context) : this.createARButton && await J.isARSupported() && this.createARButton ? J.offerSession("immersive-ar", "default", this.context) : !1;
   }
@@ -28259,6 +29188,11 @@ const va = (Hp = class extends I {
   get isActiveWebXR() {
     return !va.activeWebXRComponent || va.activeWebXRComponent === this;
   }
+  /**
+   * Called before entering a WebXR session. Sets up optional features like depth sensing, if needed.
+   * @param _mode The XR session mode being requested (immersive-ar or immersive-vr)
+   * @param args The XRSessionInit object that will be passed to the WebXR API
+   */
   onBeforeXR(t, e) {
     var i;
     if (!this.isActiveWebXR) {
@@ -28267,6 +29201,11 @@ const va = (Hp = class extends I {
     }
     va.activeWebXRComponent = this, t == "immersive-ar" && this.useDepthSensing && (e.optionalFeatures = e.optionalFeatures || [], e.optionalFeatures.push("depth-sensing"));
   }
+  /**
+   * Called when a WebXR session begins. Sets up the scene for XR by configuring controllers,
+   * AR placement, and other features based on component settings.
+   * @param args Event arguments containing information about the started XR session
+   */
   async onEnterXR(t) {
     if (!this.isActiveWebXR)
       return;
@@ -28291,9 +29230,19 @@ const va = (Hp = class extends I {
       priority: 2e4
     }));
   }
+  /**
+   * Called every frame during an active WebXR session.
+   * Updates components that depend on the current XR state.
+   * @param _args Event arguments containing information about the current XR session frame
+   */
   onUpdateXR(t) {
     this.isActiveWebXR && this._spatialGrabRaycaster && (this._spatialGrabRaycaster.enabled = this.useSpatialGrab);
   }
+  /**
+   * Called when a WebXR session ends. Restores pre-session state,
+   * removes temporary components, and cleans up resources.
+   * @param _ Event arguments containing information about the ended XR session
+   */
   onLeaveXR(t) {
     var e, i;
     if ((e = this._exitXRMenuButton) == null || e.remove(), !!this.isActiveWebXR) {
@@ -28313,19 +29262,30 @@ const va = (Hp = class extends I {
     let e = this.gameObject.getComponent(Dn);
     return !e && t && (e = this.gameObject.addComponent(Dn), this._createdComponentsInSession.push(e), e.createControllerModel = this.showControllerModels, e.createHandModel == this.showHandModels), e && (e.enabled = t), e;
   }
+  /**
+   * Creates and instantiates the user's avatar representation in the WebXR session.
+   * @param xr The active session
+   */
   async createLocalAvatar(t) {
     this._playerSync && t.running && typeof this.defaultAvatar != "boolean" && (this._playerSync.asset = this.defaultAvatar, await this._playerSync.getInstance());
   }
   // HTML UI
-  /** @deprecated use `getButtonsFactory()` or access `WebXRButtonFactory.getOrCreate()` directory */
+  /** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
   getButtonsContainer() {
     return this.getButtonsFactory();
   }
-  /** Calling this function will get the Needle WebXR button factory (it will be created if it doesnt exist yet)  
-   * @returns the Needle WebXR button factory */
+  /**
+   * Returns the WebXR button factory, creating one if it doesn't exist.
+   * Use this to access and modify WebXR UI buttons.
+   * @returns The WebXRButtonFactory instance
+   */
   getButtonsFactory() {
     return this._buttonFactory || (this._buttonFactory = vo.getOrCreate()), this._buttonFactory;
   }
+  /**
+   * Creates and sets up UI elements for WebXR interaction based on component settings
+   * and device capabilities. Handles creating AR, VR, QuickLook buttons and utility buttons like QR codes.
+   */
   handleCreatingHTML() {
     if (this.createARButton || this.createVRButton || this.useQuicklookExport) {
       if ((X.isiOS() && X.isSafari() || WT) && this.useQuicklookExport) {
@@ -28359,9 +29319,17 @@ const va = (Hp = class extends I {
       }
     }
   }
+  /**
+   * Adds a button to the UI with the specified priority.
+   * @param button The HTML element to add
+   * @param priority The button's priority value (lower numbers appear first)
+   */
   addButton(t, e) {
     this._buttons.push(t), t.setAttribute("priority", e.toString()), this.context.menu.appendChild(t);
   }
+  /**
+   * Removes all buttons created by this component from the UI.
+   */
   removeButtons() {
     for (const t of this._buttons)
       t.remove();
@@ -29004,8 +29972,17 @@ class Li extends I {
   constructor() {
     super(...arguments);
     r(this, "type", 0);
+    /**
+     * The maximum distance the light affects
+     */
     r(this, "range", 1);
+    /**
+     * The full outer angle of the spotlight cone in degrees
+     */
     r(this, "spotAngle", 1);
+    /**
+     * The angle of the inner cone in degrees for soft-edge spotlights
+     */
     r(this, "innerSpotAngle", 1);
     r(this, "_color", new le(16777215));
     r(this, "_shadowNearPlane", 0.1);
@@ -29021,6 +29998,9 @@ class Li extends I {
     r(this, "shadowWidth");
     r(this, "shadowHeight");
     r(this, "_shadowResolution");
+    /**
+     * The underlying three.js {@link ThreeLight} instance
+     */
     r(this, "light");
     r(this, "_webXRStartedListener");
     r(this, "_webXREndedListener");
@@ -29100,9 +30080,15 @@ class Li extends I {
     const i = this.light;
     i != null && i.shadow && (i.shadow.mapSize.set(e, e), i.shadow.needsUpdate = !0);
   }
+  /**
+   * Whether this light's illumination is entirely baked into lightmaps
+   */
   get isBaked() {
     return this.lightmapBakeType === 2;
   }
+  /**
+   * Checks if the GameObject itself is a {@link ThreeLight} object
+   */
   get selfIsLight() {
     if (this.gameObject.isLight === !0)
       return !0;
@@ -29114,6 +30100,11 @@ class Li extends I {
     }
     return !1;
   }
+  /**
+   * Gets the world position of the light
+   * @param vec Vector3 to store the result
+   * @returns The world position as a Vector3
+   */
   getWorldPosition(e) {
     return this.light ? this.type === 1 ? this.light.getWorldPosition(e).multiplyScalar(1) : this.light.getWorldPosition(e) : e;
   }
@@ -29141,6 +30132,10 @@ class Li extends I {
   // }
   onLeaveXR(e) {
   }
+  /**
+   * Creates the appropriate three.js light based on the configured light type
+   * and applies all settings like shadows, intensity, and color.
+   */
   createLight() {
     const e = this.selfIsLight;
     if (e && !this.light)
@@ -29190,19 +30185,33 @@ class Li extends I {
       this.isBaked ? this.light.removeFromParent() : e || this.gameObject.add(this.light);
     }
   }
+  /**
+   * Coroutine that updates the main light reference in the context
+   * if this directional light should be the main light
+   */
   *updateMainLightRoutine() {
     for (; ; ) {
       this.type === 1 && ((!this.context.mainLight || this.intensity > this.context.mainLight.intensity) && (this.context.mainLight = this), yield);
       break;
     }
   }
+  /**
+   * Updates shadow settings based on whether the shadows are set to hard or soft
+   */
   updateShadowSoftHard() {
     this.light && this.light.shadow && (this.shadows === 2 || (this.light.shadow.radius = 1, this.light.shadow.blurSamples = 1));
   }
+  /**
+   * Configures a directional light by adding and positioning its target
+   * @param dirLight The directional light to set up
+   */
   setDirectionalLight(e) {
     e.add(e.target), e.target.position.set(0, 0, -1);
   }
 }
+/**
+ * Controls whether the renderer's shadow map type can be changed when soft shadows are used
+ */
 r(Li, "allowChangingRendererShadowMapType", !0);
 Ks([
   f()
@@ -29422,7 +30431,13 @@ const m2 = S("debugnet"), Vm = class extends I {
   awake() {
     m2 && console.log(this), this.context.connection.registerProvider(this);
   }
-  /** @internal */
+  /** 
+   * Determines the websocket URL to use for networking connections.
+   * Processes the configured URL, applying localhost fallbacks when appropriate and
+   * handling URL parameter overrides if specified.
+   * @returns The formatted websocket URL string or null if no valid URL could be determined
+   * @internal
+   */
   getWebsocketUrl() {
     let t = this.url ? Vm.GetUrl(this.url, this.localhost) : null;
     if (this.urlParameterName) {
@@ -29434,6 +30449,13 @@ const m2 = S("debugnet"), Vm = class extends I {
     const i = new RegExp("(((https?)|(?<socket_prefix>wss?))://)?(www.)?(?<url>.+)", "gm").exec(t);
     return i != null && i.groups ? (i == null ? void 0 : i.groups.socket_prefix) ? t : "wss://" + (i == null ? void 0 : i.groups.url) : null;
   }
+  /**
+   * Processes a URL string applying various transformations based on network environment.
+   * Handles relative paths and localhost fallbacks for local network environments.
+   * @param url The original URL to process
+   * @param localhostFallback Alternative URL to use when on a local network
+   * @returns The processed URL string or null/undefined if input was invalid
+   */
   static GetUrl(t, e) {
     let i = t;
     const s = Vm.IsLocalNetwork() && e;
@@ -29443,6 +30465,13 @@ const m2 = S("debugnet"), Vm = class extends I {
     }
     return i;
   }
+  /**
+   * Determines if the current connection is on a local network.
+   * Useful for applying different networking configurations in local development environments.
+   * This is the same as calling {@link isLocalNetwork}.
+   * @param hostname Optional hostname to check instead of the current window location
+   * @returns True if the connection is on a local network, false otherwise
+   */
   static IsLocalNetwork(t = window.location.hostname) {
     return pi(t);
   }
@@ -33625,9 +34654,19 @@ function Ub(n) {
   return e != null && e.length ? e : n;
 }
 class DA {
+  /**
+   * Creates a new PreLoadScheduler instance
+   * @param rooms The SceneSwitcher that this scheduler belongs to
+   * @param ahead Number of scenes to preload ahead of current scene
+   * @param behind Number of scenes to preload behind current scene
+   * @param maxConcurrent Maximum number of concurrent preloads allowed
+   */
   constructor(t, e = 1, i = 1, s = 2) {
+    /** Maximum number of scenes to preload ahead of the current scene */
     r(this, "maxLoadAhead");
+    /** Maximum number of scenes to preload behind the current scene */
     r(this, "maxLoadBehind");
+    /** Maximum number of scenes that can be preloaded concurrently */
     r(this, "maxConcurrent");
     r(this, "_isRunning", !1);
     r(this, "_switcher");
@@ -33635,6 +34674,10 @@ class DA {
     r(this, "_maxConcurrentLoads", 1);
     this._switcher = t, this.maxLoadAhead = e, this.maxLoadBehind = i, this.maxConcurrent = s;
   }
+  /**
+   * Starts the preloading process after a specified delay
+   * @param delay Time in milliseconds to wait before starting preload
+   */
   begin(t) {
     if (this._isRunning)
       return;
@@ -33660,12 +34703,23 @@ class DA {
       }
     }, 200);
   }
+  /**
+   * Stops the preloading process
+   */
   stop() {
     this._isRunning = !1;
   }
+  /**
+   * Checks if a new scene can be loaded based on current load limits
+   * @returns True if a new scene can be loaded, false otherwise
+   */
   canLoadNewScene() {
     return this._loadTasks.length < this._maxConcurrentLoads;
   }
+  /**
+   * Checks if all scenes in the SceneSwitcher have been loaded
+   * @returns True if all scenes are loaded, false otherwise
+   */
   allLoaded() {
     if (this._switcher.scenes) {
       for (const t of this._switcher.scenes)
@@ -33676,12 +34730,24 @@ class DA {
   }
 }
 class LA {
+  /**
+   * Creates a new LoadTask and begins loading immediately
+   * @param index The index of the scene in the scenes array
+   * @param asset The AssetReference to preload
+   * @param tasks The collection of active load tasks
+   */
   constructor(t, e, i) {
+    /** The index of the scene in the scenes array */
     r(this, "index");
+    /** The AssetReference to be loaded */
     r(this, "asset");
+    /** The collection of active load tasks this task belongs to */
     r(this, "tasks");
     this.index = t, this.asset = e, this.tasks = i, i.push(this), this.awaitLoading();
   }
+  /**
+   * Asynchronously loads the asset and removes this task from the active tasks list when complete
+   */
   async awaitLoading() {
     this.asset && !this.asset.isLoaded() && (Zt && console.log("Preload start: " + this.asset.url, this.index), await this.asset.preload(), Zt && console.log("Preload finished: " + this.asset.url, this.index));
     const t = this.tasks.indexOf(this);
@@ -35005,12 +36071,23 @@ class An extends I {
     r(this, "onEnter");
     r(this, "onStay");
     r(this, "onExit");
+    /** Array of triggers currently intersecting with this receiver */
     r(this, "currentIntersected", []);
+    /** Array of triggers that intersected with this receiver in the previous frame */
     r(this, "lastIntersected", []);
   }
+  /** 
+   * Initializes the receiver and logs debug info if enabled
+   * @internal
+   */
   start() {
     wc && console.log(this.name, this.triggerMask, this);
   }
+  /**
+   * Checks for intersections with spatial triggers and fires appropriate events
+   * Handles enter, stay, and exit events for all relevant triggers
+   * @internal
+   */
   update() {
     this.currentIntersected.length = 0;
     for (const e of yf.triggers)
@@ -35023,14 +36100,26 @@ class An extends I {
       this.lastIntersected.indexOf(e) < 0 && this.onEnterTrigger(e), this.onStayTrigger(e);
     this.lastIntersected.length = 0, this.lastIntersected.push(...this.currentIntersected);
   }
+  /**
+   * Handles trigger enter events.
+   * @param trigger The spatial trigger that was entered
+   */
   onEnterTrigger(e) {
     var i;
     wc && console.log("ENTER TRIGGER", this.name, e.name, this, e), e.raiseOnEnterEvent(this), (i = this.onEnter) == null || i.invoke();
   }
+  /**
+   * Handles trigger exit events.
+   * @param trigger The spatial trigger that was exited
+   */
   onExitTrigger(e) {
     var i;
     wc && console.log("EXIT TRIGGER", this.name, e.name), e.raiseOnExitEvent(this), (i = this.onExit) == null || i.invoke();
   }
+  /**
+   * Handles trigger stay events.
+   * @param trigger The spatial trigger that the receiver is staying in
+   */
   onStayTrigger(e) {
     var i;
     e.raiseOnStayEvent(this), (i = this.onStay) == null || i.invoke();
@@ -35053,38 +36142,66 @@ const Td = (Xp = class extends I {
   constructor() {
     super(...arguments);
     r(this, "triggerMask");
+    /** Box helper component used to visualize and calculate the trigger area */
     r(this, "boxHelper");
   }
+  /**
+   * Initializes the trigger and logs debug info if enabled
+   */
   start() {
     wc && console.log(this.name, this.triggerMask, this);
   }
+  /**
+   * Registers this trigger in the global registry and sets up debug visualization if enabled
+   */
   onEnable() {
     var t;
     Td.triggers.push(this), this.boxHelper || (this.boxHelper = C.addComponent(this.gameObject, Ci), (t = this.boxHelper) == null || t.showHelper(null, wc));
   }
+  /**
+   * Removes this trigger from the global registry when disabled
+   */
   onDisable() {
     Td.triggers.splice(Td.triggers.indexOf(this), 1);
   }
+  /**
+   * Tests if an object is inside this trigger's box
+   * @param obj The object to test against this trigger
+   * @returns True if the object is inside the trigger box
+   */
   test(t) {
     return this.boxHelper ? this.boxHelper.isInBox(t) ?? !1 : !1;
   }
   // private args: SpatialTriggerEventArgs = new SpatialTriggerEventArgs();
+  /**
+   * Raises the onEnter event on any SpatialTriggerReceiver components attached to this trigger's GameObject
+   * @param rec The receiver that entered this trigger
+   */
   raiseOnEnterEvent(t) {
     C.foreachComponent(this.gameObject, (e) => {
       e !== t && e instanceof An && e.onEnterTrigger(this);
     }, !1);
   }
+  /**
+   * Raises the onStay event on any SpatialTriggerReceiver components attached to this trigger's GameObject
+   * @param rec The receiver that is staying in this trigger
+   */
   raiseOnStayEvent(t) {
     C.foreachComponent(this.gameObject, (e) => {
       e !== t && e instanceof An && e.onStayTrigger(this);
     }, !1);
   }
+  /**
+   * Raises the onExit event on any SpatialTriggerReceiver components attached to this trigger's GameObject
+   * @param rec The receiver that exited this trigger
+   */
   raiseOnExitEvent(t) {
     C.foreachComponent(this.gameObject, (e) => {
       e !== t && e instanceof An && e.onExitTrigger(this);
     }, !1);
   }
-}, r(Xp, "triggers", []), Xp);
+}, /** Global registry of all active spatial triggers in the scene */
+r(Xp, "triggers", []), Xp);
 let yf = Td;
 xh([
   f()
@@ -35098,6 +36215,7 @@ const Pi = S("debugspectator");
 class w_ extends I {
   constructor() {
     super(...arguments);
+    /** Reference to the Camera component on this GameObject */
     r(this, "cam", null);
     r(this, "useKeys", !0);
     r(this, "_mode", 0);
@@ -35112,29 +36230,42 @@ class w_ extends I {
     r(this, "_debug");
     r(this, "_networking");
   }
+  /** Gets the current spectator perspective mode */
   get mode() {
     return this._mode;
   }
+  /** Sets the current spectator perspective mode */
   set mode(e) {
     this._mode = e;
   }
-  /** if this user is currently spectating someone else */
+  /** Returns whether this user is currently spectating another user */
   get isSpectating() {
     var e;
     return ((e = this._handler) == null ? void 0 : e.currentTarget) !== void 0;
   }
+  /**
+   * Checks if this instance is spectating the user with the given ID
+   * @param userId The user ID to check
+   * @returns True if spectating the specified user, false otherwise
+   */
   isSpectatingUser(e) {
     var i;
     return ((i = this.target) == null ? void 0 : i.userId) === e;
   }
+  /**
+   * Checks if the user with the specified ID is following this user
+   * @param userId The user ID to check
+   * @returns True if the specified user is following this user, false otherwise
+   */
   isFollowedBy(e) {
     var i;
     return (i = this.followers) == null ? void 0 : i.includes(e);
   }
-  /** list of other users that are following me */
+  /** List of user IDs that are currently following the user */
   get followers() {
     return this._networking.followers;
   }
+  /** Stops the current spectating session */
   stopSpectating() {
     if (this.context.isInXR) {
       this.followSelf();
@@ -35142,10 +36273,14 @@ class w_ extends I {
     }
     this.target = void 0;
   }
+  /** Gets the local player's connection ID */
   get localId() {
     return this.context.connection.connectionId ?? "local";
   }
-  /** player view to follow */
+  /** 
+   * Sets the player view to follow
+   * @param target The PlayerView to follow, or undefined to stop spectating
+   */
   set target(e) {
     var i;
     if (this._handler) {
@@ -35153,13 +36288,16 @@ class w_ extends I {
       e === void 0 || this.context.isInXR === !1 && (o == null ? void 0 : o.currentObject) === e.currentObject ? this._handler.currentTarget !== void 0 && (this._handler.disable(), C.setActive(this.gameObject, !1), this.orbit && (this.orbit.enabled = !0), this._networking.onSpectatedObjectChanged(e, s)) : this._handler.currentTarget !== e && (this._handler.set(e), C.setActive(this.gameObject, !0), this.orbit && (this.orbit.enabled = !1), this._networking.onSpectatedObjectChanged(e, s));
     }
   }
+  /** Gets the currently followed player view */
   get target() {
     var e;
     return (e = this._handler) == null ? void 0 : e.currentTarget;
   }
+  /** Sends a network request for all users to follow this player */
   requestAllFollowMe() {
     this._networking.onRequestFollowMe();
   }
+  /** Determines if the camera is spectating the local player */
   get isSpectatingSelf() {
     var e, i;
     return this.isSpectating && ((e = this.target) == null ? void 0 : e.currentObject) === ((i = this.context.players.getPlayerView(this.localId)) == null ? void 0 : i.currentObject);
@@ -35175,26 +36313,48 @@ class w_ extends I {
     var e, i;
     this.stopSpectating(), (e = this._handler) == null || e.destroy(), (i = this._networking) == null || i.destroy();
   }
+  /**
+   * Checks if the current platform supports spectator mode
+   * @returns True if the platform is supported, false otherwise
+   */
   isSupportedPlatform() {
     const e = window.navigator.userAgent, i = /Windows|MacOS/.test(e), s = /Windows NT/.test(e) && /Edg/.test(e) && !/Win64/.test(e);
     return i && !s;
   }
+  /**
+   * Called before entering WebXR mode
+   * @param _evt The WebXR event
+   */
   onBeforeXR(e) {
     this.isSupportedPlatform() && C.setActive(this.gameObject, !0);
   }
+  /**
+   * Called when entering WebXR mode
+   * @param _evt The WebXR event
+   */
   onEnterXR(e) {
     this.isSupportedPlatform() && (Pi && console.log(this.context.mainCamera), this.context.mainCamera && this.followSelf());
   }
+  /**
+   * Called when exiting WebXR mode
+   * @param _evt The WebXR event
+   */
   onLeaveXR(e) {
     var i, s;
     this.context.removeCamera(this.cam), C.setActive(this.gameObject, !1), this.orbit && (this.orbit.enabled = !0), (i = this._handler) == null || i.set(void 0), (s = this._handler) == null || s.disable(), this.isSpectatingSelf && this.stopSpectating();
   }
+  /**
+   * Sets the target to follow the local player
+   */
   followSelf() {
     this.target = this.context.players.getPlayerView(this.context.connection.connectionId), this.target || (this.context.players.setPlayerView(this.localId, this.context.mainCamera, ur.Headset), this.target = this.context.players.getPlayerView(this.localId)), Pi && console.log("Follow self", this.target);
   }
   // TODO: only show Spectator cam for DesktopVR;
   // don't show for AR, don't show on Quest
   // TODO: properly align cameras on enter/exit VR, seems currently spectator cam breaks alignment
+  /**
+   * Called after the main rendering pass to render the spectator view
+   */
   onAfterRender() {
     var d, u, p;
     if (!this.cam)
@@ -35224,6 +36384,9 @@ class w_ extends I {
     const h = e.xr.isPresenting;
     e.xr.isPresenting = !1, e.setSize(this.context.domWidth, this.context.domHeight), e.render(this.context.scene, c), e.xr.isPresenting = h, e.xr.enabled = i, s ? e.setRenderTarget(s) : a.bindXRFramebuffer && a.bindXRFramebuffer(o), this.resetAvatarFlags();
   }
+  /**
+   * Updates avatar visibility flags for rendering in spectator mode
+   */
   setAvatarFlagsBeforeRender() {
     const e = this._mode === 0;
     for (const i of _t.instances)
@@ -35237,6 +36400,9 @@ class w_ extends I {
           a.UpdateVisible(s);
       }
   }
+  /**
+   * Restores avatar visibility flags after spectator rendering
+   */
   resetAvatarFlags() {
     var e;
     for (const i of _t.instances)
@@ -35263,9 +36429,14 @@ class rE {
     r(this, "currentObject");
     this.context = t, this.cam = e, this.spectator = i;
   }
+  /** Gets the currently targeted player view */
   get currentTarget() {
     return this.view;
   }
+  /**
+   * Sets the target player view to follow
+   * @param view The PlayerView to follow
+   */
   set(t) {
     const e = t == null ? void 0 : t.currentObject;
     if (!e) {
@@ -35274,13 +36445,19 @@ class rE {
     }
     e !== this.currentObject && (this.currentObject = e, this.view = t, this.follow || (this.follow = C.addComponent(this.cam.gameObject, Kr)), this.target || (this.target = new D()), e.add(this.target), this.follow.enabled = !0, this.follow.target = this.target, Pi && console.log("FOLLOW", e), this.context.isInXR ? this.context.removeCamera(this.cam) : this.context.setCurrentCamera(this.cam));
   }
+  /** Disables the spectator following behavior */
   disable() {
     Pi && console.log("STOP FOLLOW", this.currentObject), this.view = void 0, this.currentObject = void 0, this.context.removeCamera(this.cam), this.follow && (this.follow.enabled = !1);
   }
+  /** Cleans up resources used by the handler */
   destroy() {
     var t;
     (t = this.target) == null || t.removeFromParent(), this.follow && C.destroy(this.follow);
   }
+  /**
+   * Updates the camera position and orientation based on the spectator mode
+   * @param mode The current spectator mode (first or third person)
+   */
   update(t) {
     var s, o, a, l, c, h;
     if (((s = this.currentTarget) == null ? void 0 : s.isConnected) === !1 || ((o = this.currentTarget) == null ? void 0 : o.removed) === !0) {
@@ -35325,6 +36502,9 @@ class lE {
       o > 1 ? this.spectator.stopSpectating() : this.context.input.getPointerClicked(0) && o < 0.3 && this.trySelectObject();
     });
   }
+  /**
+   * Attempts to select an avatar to spectate through raycasting
+   */
   trySelectObject() {
     const t = new En();
     t.setMask(16777215);
@@ -35344,11 +36524,12 @@ class lE {
 }
 class cE {
   constructor(t, e, i) {
-    /** the user that is following */
+    /** The user ID that is following */
     r(this, "guid");
     r(this, "dontSave", !0);
-    /** the user being followed */
+    /** The user ID being followed */
     r(this, "targetUserId");
+    /** Indicates if the user stopped following */
     r(this, "stoppedFollowing");
     this.guid = t, this.targetUserId = e, this.stoppedFollowing = i;
   }
@@ -35362,6 +36543,7 @@ class hE {
 }
 class dE {
   constructor(t, e) {
+    /** List of user IDs currently following this player */
     r(this, "followers", []);
     r(this, "context");
     r(this, "spectator");
@@ -35372,20 +36554,35 @@ class dE {
     r(this, "_enforceFollowInterval");
     this.context = t, this.spectator = e, this._followerEventMethod = this.onFollowerEvent.bind(this), this._requestFollowMethod = this.onRequestFollowEvent.bind(this), this._joinedRoomMethod = this.onUserJoinedRoom.bind(this);
   }
+  /**
+   * Initializes network event listeners
+   */
   awake() {
     this.context.connection.beginListen("spectator-follower-changed", this._followerEventMethod), this.context.connection.beginListen("spectator-request-follow", this._requestFollowMethod), this.context.connection.beginListen(ie.JoinedRoom, this._joinedRoomMethod), this.context.domElement.addEventListener("keydown", (t) => {
       this.spectator.useKeys && (t.key === "f" ? this.onRequestFollowMe() : t.key === "Escape" && this.onRequestFollowMe(!0));
     });
   }
+  /**
+   * Removes network event listeners
+   */
   destroy() {
     this.context.connection.stopListen("spectator-follower-changed", this._followerEventMethod), this.context.connection.stopListen("spectator-request-follow", this._requestFollowMethod), this.context.connection.stopListen(ie.JoinedRoom, this._joinedRoomMethod);
   }
+  /**
+   * Notifies other users about spectating target changes
+   * @param target The new target being spectated
+   * @param _prevId The previous target's user ID
+   */
   onSpectatedObjectChanged(t, e) {
     if (Pi && console.log(this.context.connection.connectionId, "onSpectatedObjectChanged", t, e), this.context.connection.connectionId) {
       const i = (t == null ? void 0 : t.userId) === void 0, s = i ? e : t == null ? void 0 : t.userId, o = new cE(this.context.connection.connectionId, s, i);
       this.context.connection.send("spectator-follower-changed", o);
     }
   }
+  /**
+   * Requests other users to follow this player or stop following
+   * @param stop Whether to request users to stop following
+   */
   onRequestFollowMe(t = !1) {
     if (Pi && console.log("Request follow", this.context.connection.connectionId), this.context.connection.connectionId) {
       this.spectator.stopSpectating();
@@ -35393,9 +36590,16 @@ class dE {
       this.context.connection.send("spectator-request-follow", i);
     }
   }
+  /**
+   * Handles room join events
+   */
   onUserJoinedRoom() {
     S("followme") && this.onRequestFollowMe();
   }
+  /**
+   * Processes follower status change events from the network
+   * @param evt The follower change event data
+   */
   onFollowerEvent(t) {
     const e = t.targetUserId, i = t.guid;
     if (Pi && console.log(t), e === this.context.connection.connectionId)
@@ -35405,12 +36609,20 @@ class dE {
       } else
         this.followers.includes(i) || (this.followers.push(i), this.removeDisconnectedFollowers(), console.log(i, "follows you", this.followers.length));
   }
+  /**
+   * Removes followers that are no longer connected to the room
+   */
   removeDisconnectedFollowers() {
     for (let t = this.followers.length - 1; t >= 0; t--) {
       const e = this.followers[t];
       this.context.connection.userIsInRoom(e) === !1 && this.followers.splice(t, 1);
     }
   }
+  /**
+   * Handles follow requests from other users
+   * @param evt The follow request event
+   * @returns True if the request was handled successfully
+   */
   onRequestFollowEvent(t) {
     if (this._lastRequestFollowUser = t, t.userId === this.context.connection.connectionId)
       this.spectator.stopSpectating();
@@ -35425,6 +36637,9 @@ class dE {
     }
     return !0;
   }
+  /**
+   * Periodically retries following a user if the initial attempt failed
+   */
   enforceFollow() {
     this._enforceFollowInterval || (this._enforceFollowInterval = setInterval(() => {
       this._lastRequestFollowUser === void 0 || this._lastRequestFollowUser.userId && this.spectator.isFollowedBy(this._lastRequestFollowUser.userId) ? (clearInterval(this._enforceFollowInterval), this._enforceFollowInterval = void 0) : (Pi && console.log("REQUEST FOLLOW AGAIN", this._lastRequestFollowUser.userId), this.onRequestFollowEvent(this._lastRequestFollowUser));
@@ -36934,6 +38149,11 @@ class wl extends I {
     r(this, "scaleSnap", 0.25);
     r(this, "_control");
     r(this, "orbit");
+    /**
+     * Event handler for when dragging state changes.
+     * Disables orbit controls during dragging and requests ownership of the transform if it's synchronized.
+     * @param event The drag change event
+     */
     r(this, "onControlChangedEvent", (e) => {
       const i = this.orbit;
       if (i && (i.enabled = !e.value), e.value) {
@@ -36941,6 +38161,18 @@ class wl extends I {
         s && s.requestOwnership();
       }
     });
+    /**
+     * Handles keyboard shortcuts for transform operations:
+     * - Q: Toggle local/world space
+     * - W: Translation mode
+     * - E: Rotation mode
+     * - R: Scale mode
+     * - Shift: Enable snapping (while held)
+     * - +/-: Adjust gizmo size
+     * - X/Y/Z: Toggle visibility of respective axis
+     * - Spacebar: Toggle controls enabled state
+     * @param event The keyboard event
+     */
     r(this, "windowKeyDownListener", (e) => {
       if (this.enabled && this._control)
         switch (e.keyCode) {
@@ -36981,6 +38213,11 @@ class wl extends I {
             break;
         }
     });
+    /**
+     * Handles keyboard key release events.
+     * Currently only handles releasing Shift key to disable snapping.
+     * @param event The keyboard event
+     */
     r(this, "windowKeyUpListener", (e) => {
       if (this.enabled)
         switch (e.keyCode) {
@@ -36991,8 +38228,8 @@ class wl extends I {
     });
   }
   /**
-   * Get the underlying three.js TransformControls instance.
-   * @returns The TransformControls instance.
+   * Gets the underlying three.js {@link TransformControls} instance.
+   * @returns The TransformControls instance or undefined if not initialized.
    */
   get control() {
     return this._control;
@@ -37016,9 +38253,17 @@ class wl extends I {
     var e, i, s;
     (i = (e = this._control) == null ? void 0 : e.getHelper()) == null || i.removeFromParent(), (s = this._control) == null || s.removeEventListener("dragging-changed", this.onControlChangedEvent), window.removeEventListener("keydown", this.windowKeyDownListener), window.removeEventListener("keyup", this.windowKeyUpListener);
   }
+  /**
+   * Enables grid snapping for transform operations according to set snap values.
+   * This applies the translationSnap, rotationSnapAngle, and scaleSnap properties to the controls.
+   */
   enableSnapping() {
     this._control && (this._control.setTranslationSnap(this.translationSnap), this._control.setRotationSnap(Pn.degToRad(this.rotationSnapAngle)), this._control.setScaleSnap(this.scaleSnap));
   }
+  /**
+   * Disables grid snapping for transform operations.
+   * Removes all snapping constraints from the transform controls.
+   */
   disableSnapping() {
     this._control && (this._control.setTranslationSnap(null), this._control.setRotationSnap(null), this._control.setScaleSnap(null));
   }