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

package/src/engine-components/Component.ts

@@ -23,57 +23,167 @@ import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.
 // }
 
 /**
- * All {@type Object3D} types that are loaded in Needle Engine do automatically receive the GameObject extensions like `addComponent` etc.  
- * Many of the GameObject methods can be imported directly via `@needle-tools/engine` as well:
+ * Base class for objects in Needle Engine. Extends {@link Object3D} from three.js.
+ * GameObjects can have components attached to them, which can be used to add functionality to the object.
+ * They manage their components and provide methods to add, remove and get components.
+ * 
+ * All {@link Object3D} types loaded in Needle Engine have methods like {@link addComponent}.
+ * These methods are available directly on the GameObject instance:
+ * ```typescript
+ * target.addComponent(MyComponent);
+ * ```
+ * 
+ * And can be called statically on the GameObject class as well:
  * ```typescript
- * import { addComponent } from "@needle-tools/engine";
+ * GameObject.setActive(target, true);
  * ```
  */
 export abstract class GameObject extends Object3D implements Object3D, IGameObject {
 
-    // these are implemented via threejs object extensions
+    /** 
+     * Indicates if the GameObject is currently active. Inactive GameObjects will not be rendered or updated.
+     * When the activeSelf state changes, components will receive {@link Component.onEnable} or {@link Component.onDisable} callbacks.
+     */
     abstract activeSelf: boolean;
 
-    /** @deprecated use `addComponent` */
+    /** @deprecated Use {@link addComponent} instead */
     // eslint-disable-next-line deprecation/deprecation
     abstract addNewComponent<T extends IComponent>(type: ConstructorConcrete<T>, init?: ComponentInit<T>): T;
-    /** creates a new component on this gameObject */
+    
+    /** 
+     * Creates a new component on this gameObject or adds an existing component instance 
+     * @param comp Component type constructor or existing component instance
+     * @param init Optional initialization values for the component
+     * @returns The newly created or added component
+     */
     abstract addComponent<T extends IComponent>(comp: T | ConstructorConcrete<T>, init?: ComponentInit<T>): T;
+    
+    /**
+     * Removes a component from this GameObject
+     * @param comp Component instance to remove
+     * @returns The removed component
+     */
     abstract removeComponent<T extends IComponent>(comp: T): T;
+    
+    /**
+     * Gets an existing component of the specified type or adds a new one if it doesn't exist
+     * @param typeName Constructor of the component type to get or add
+     * @returns The existing or newly added component
+     */
     abstract getOrAddComponent<T>(typeName: ConstructorConcrete<T> | null): T;
+    
+    /**
+     * Gets a component of the specified type attached to this GameObject
+     * @param type Constructor of the component type to get
+     * @returns The component if found, otherwise null
+     */
     abstract getComponent<T>(type: Constructor<T>): T | null;
+    
+    /**
+     * Gets all components of the specified type attached to this GameObject
+     * @param type Constructor of the component type to get
+     * @param arr Optional array to populate with the components
+     * @returns Array of components
+     */
     abstract getComponents<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+    
+    /**
+     * Gets a component of the specified type in this GameObject's children hierarchy
+     * @param type Constructor of the component type to get
+     * @returns The first matching component if found, otherwise null
+     */
     abstract getComponentInChildren<T>(type: Constructor<T>): T | null;
+    
+    /**
+     * Gets all components of the specified type in this GameObject's children hierarchy
+     * @param type Constructor of the component type to get
+     * @param arr Optional array to populate with the components
+     * @returns Array of components
+     */
     abstract getComponentsInChildren<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+    
+    /**
+     * Gets a component of the specified type in this GameObject's parent hierarchy
+     * @param type Constructor of the component type to get
+     * @returns The first matching component if found, otherwise null
+     */
     abstract getComponentInParent<T>(type: Constructor<T>): T | null;
+    
+    /**
+     * Gets all components of the specified type in this GameObject's parent hierarchy
+     * @param type Constructor of the component type to get
+     * @param arr Optional array to populate with the components
+     * @returns Array of components
+     */
     abstract getComponentsInParent<T>(type: Constructor<T>, arr?: T[]): Array<T>;
 
 
+    /**
+     * The position of this GameObject in world space
+     */
     abstract get worldPosition(): Vector3
     abstract set worldPosition(val: Vector3);
+    
+    /**
+     * The rotation of this GameObject in world space as a quaternion
+     */
     abstract set worldQuaternion(val: Quaternion);
     abstract get worldQuaternion(): Quaternion;
+    
+    /**
+     * The rotation of this GameObject in world space in euler angles (degrees)
+     */
     abstract set worldRotation(val: Vector3);
     abstract get worldRotation(): Vector3;
+    
+    /**
+     * The scale of this GameObject in world space
+     */
     abstract set worldScale(val: Vector3);
     abstract get worldScale(): Vector3;
 
+    /**
+     * The forward direction vector of this GameObject in world space
+     */
     abstract get worldForward(): Vector3;
+    
+    /**
+     * The right direction vector of this GameObject in world space
+     */
     abstract get worldRight(): Vector3;
+    
+    /**
+     * The up direction vector of this GameObject in world space
+     */
     abstract get worldUp(): Vector3;
 
+    /**
+     * Unique identifier for this GameObject
+     */
     guid: string | undefined;
 
-    // Added to the threejs Object3D prototype
+    /**
+     * Destroys this GameObject and all its components.
+     * Internally, this is added to the three.js {@link Object3D} prototype.
+     */
     abstract destroy();
 
 
-
-
+    /**
+     * Checks if a GameObject has been destroyed
+     * @param go The GameObject to check
+     * @returns True if the GameObject has been destroyed
+     */
     public static isDestroyed(go: Object3D): boolean {
         return isDestroyed(go);
     }
 
+    /**
+     * 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
+     */
     public static setActive(go: Object3D, active: boolean, processStart: boolean = true) {
         if (!go) return;
         setActive(go, active);
@@ -84,47 +194,68 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
             main.processStart(Context.Current, go);
     }
 
-    /** 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
+     */
     public static isActiveSelf(go: Object3D): boolean {
         return isActiveSelf(go);
     }
 
-    /** 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
+     */
     public static isActiveInHierarchy(go: Object3D): boolean {
         return isActiveInHierarchy(go);
     }
 
+    /**
+     * Marks a GameObject to be rendered using instancing
+     * @param go The GameObject to mark
+     * @param instanced Whether the GameObject should use instanced rendering
+     */
     public static markAsInstancedRendered(go: Object3D, instanced: boolean) {
         markAsInstancedRendered(go, instanced);
     }
 
+    /**
+     * Checks if a GameObject is using instanced rendering
+     * @param instance The GameObject to check
+     * @returns True if the GameObject is using instanced rendering
+     */
     public static isUsingInstancing(instance: Object3D): boolean { return isUsingInstancing(instance); }
 
-    /** 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
      */
     public static foreachComponent(instance: Object3D, cb: (comp: Component) => any, recursive: boolean = true): any {
         return foreachComponent(instance, cb as (comp: IComponent) => any, recursive);
     }
 
-    /** 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
      */
     public static instantiateSynced(instance: GameObject | Object3D | null, opts: SyncInstantiateOptions): GameObject | null {
         if (!instance) return null;
         return syncInstantiate(instance, opts) as GameObject | null;
     }
 
-    /** Creates a new instance of the provided object (like cloning it including all components and children) 
-     * @param instance object to instantiate
-     * @param opts options for the instantiation (e.g. with what parent, position, etc.)
-    */
+    /**
+     * Creates a new instance of the provided object (like cloning it including all components and children)
+     * @param instance Object to instantiate
+     * @param opts Options for the instantiation (e.g. with what parent, position, etc.)
+     * @returns The newly created instance
+     */
     public static instantiate(instance: AssetReference, opts?: IInstantiateOptions | null | undefined): Promise<Object3D | null>
     public static instantiate(instance: GameObject | Object3D, opts?: IInstantiateOptions | null | undefined): GameObject
     public static instantiate(instance: AssetReference | GameObject | Object3D, opts: IInstantiateOptions | null | undefined = null): GameObject | Promise<Object3D | null> {
@@ -134,9 +265,12 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
         return instantiate(instance as GameObject | Object3D, opts) as GameObject;
     }
 
-    /** 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
+     */
     public static destroySynced(instance: Object3D | Component, context?: Context, recursive: boolean = true) {
         if (!instance) return;
         const go = instance as GameObject;
@@ -144,16 +278,20 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
         syncDestroy(go as any, context.connection, recursive);
     }
 
-    /** 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
      */
     public static destroy(instance: Object3D | Component, recursive: boolean = true) {
         return destroy(instance, recursive);
     }
 
     /**
-     * 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
      */
     public static add(instance: Object3D | null | undefined, parent: Object3D, context?: Context) {
         if (!instance || !parent) return;
@@ -183,6 +321,7 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
 
     /**
      * Removes the object from its parent and deactivates all of its components
+     * @param instance Object to remove
      */
     public static remove(instance: Object3D | null | undefined) {
         if (!instance) return;
@@ -194,14 +333,22 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
         }, true);
     }
 
-    /** 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
+     */
     public static invokeOnChildren(go: Object3D | null | undefined, functionName: string, ...args: any) {
         this.invoke(go, functionName, true, args);
     }
 
-    /** 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
      */
     public static invoke(go: Object3D | null | undefined, functionName: string, children: boolean = false, ...args: any) {
         if (!go) return;
@@ -220,38 +367,53 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     }
 
     /**
-     * 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
      */
     public static addComponent<T extends IComponent>(go: IGameObject | Object3D, instanceOrType: T | ConstructorConcrete<T>, init?: ComponentInit<T>, opts?: { callAwake: boolean }): T {
         return addComponent(go, instanceOrType, init, opts);
     }
 
     /**
-     * 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
      */
     public static moveComponent<T extends IComponent>(go: IGameObject | Object3D, instance: T | ConstructorConcrete<T>): T {
         return addComponent(go, instance);
     }
 
-    /** 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
      */
     public static removeComponent<T extends IComponent>(instance: T): T {
         removeComponent(instance.gameObject, instance as any);
         return instance;
     }
 
+    /**
+     * 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
+     */
     public static getOrAddComponent<T extends IComponent>(go: IGameObject | Object3D, typeName: ConstructorConcrete<T>): T {
         return getOrAddComponent<any>(go, typeName);
     }
 
-    /** 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
+     */
     public static getComponent<T extends IComponent>(go: IGameObject | Object3D | null, typeName: Constructor<T> | null): T | null {
         if (go === null) return null;
         // if names are minified we could also use the type store and work with strings everywhere
@@ -261,42 +423,99 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
         return getComponent(go, typeName as any);
     }
 
+    /**
+     * 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
+     */
     public static getComponents<T extends IComponent>(go: IGameObject | Object3D | null, typeName: Constructor<T>, arr: T[] | null = null): T[] {
         if (go === null) return arr ?? [];
         return getComponents(go, typeName, arr);
     }
 
+    /**
+     * 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
+     */
     public static findByGuid(guid: string, hierarchy: Object3D): GameObject | Component | null | undefined {
         const res = findByGuid(guid, hierarchy);
         return res as GameObject | Component | null | undefined;
     }
 
+    /**
+     * 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
+     */
     public static findObjectOfType<T extends IComponent>(typeName: Constructor<T>, context?: Context | Object3D, includeInactive: boolean = true): T | null {
         return findObjectOfType(typeName, context ?? Context.Current, includeInactive);
     }
 
+    /**
+     * 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
+     */
     public static findObjectsOfType<T extends IComponent>(typeName: Constructor<T>, context?: Context | Object3D): Array<T> {
         const arr = [];
         findObjectsOfType(typeName, arr, context);
         return arr;
     }
 
+    /**
+     * 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
+     */
     public static getComponentInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>): T | null {
         return getComponentInChildren(go, typeName);
     }
 
+    /**
+     * 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
+     */
     public static getComponentsInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>, arr: T[] | null = null): Array<T> {
         return getComponentsInChildren<T>(go, typeName, arr ?? undefined) as T[]
     }
 
+    /**
+     * 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
+     */
     public static getComponentInParent<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>): T | null {
         return getComponentInParent(go, typeName);
     }
 
+    /**
+     * 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
+     */
     public static getComponentsInParent<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>, arr: Array<T> | null = null): Array<T> {
         return getComponentsInParent(go, typeName, arr);
     }
 
+    /**
+     * Gets all components on the gameObject
+     * @param go GameObject to get components from
+     * @returns Array of all components
+     */
     public static getAllComponents(go: IGameObject | Object3D): Component[] {
         const componentsList = go.userData?.components;
         if (!componentsList) return [];
@@ -304,6 +523,11 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
         return newList;
     }
 
+    /**
+     * Iterates through all components on the gameObject
+     * @param go GameObject to iterate components on
+     * @returns Generator yielding each component
+     */
     public static *iterateComponents(go: IGameObject | Object3D) {
         const list = go?.userData?.components;
         if (list && Array.isArray(list)) {
@@ -346,27 +570,43 @@ export abstract class Component implements IComponent, EventTarget,
     Partial<INeedleXRSessionEventReceiver>,
     Partial<IPointerEventHandler>
 {
-    /** @internal */
+    /** 
+     * Indicates whether this object is a component
+     * @internal 
+     */
     get isComponent(): boolean { return true; }
 
     private __context: Context | undefined;
-    /** 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(): Context {
         return this.__context ?? Context.Current;
     }
     set context(context: Context) {
         this.__context = context;
     }
-    /** 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(): 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(): number {
         return this.gameObject?.userData?.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(): string {
         if (this.gameObject?.name) {
             return this.gameObject.name;
@@ -384,7 +624,11 @@ export abstract class Component implements IComponent, EventTarget,
             this.__name = str;
         }
     }
-    /** @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(): string {
         return this.gameObject?.userData.tag;
     }
@@ -394,7 +638,11 @@ export abstract class Component implements IComponent, EventTarget,
             this.gameObject.userData.tag = str;
         }
     }
-    /** 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() {
         return this.gameObject?.userData.static;
     }
@@ -408,7 +656,11 @@ export abstract class Component implements IComponent, EventTarget,
     //     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(): boolean {
         if (this.destroyed) return false;
         if (this.__isEnabled === false) return false;
@@ -426,6 +678,7 @@ export abstract class Component implements IComponent, EventTarget,
     private get __isActive(): boolean {
         return this.gameObject.visible;
     }
+    
     private get __isActiveInHierarchy(): boolean {
         if (!this.gameObject) return false;
         const res = this.gameObject[activeInHierarchyFieldName];
@@ -438,139 +691,286 @@ export abstract class Component implements IComponent, EventTarget,
         this.gameObject[activeInHierarchyFieldName] = val;
     }
 
-    /** 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
+     */
     gameObject!: GameObject;
-    /** the unique identifier for this component */
+    
+    /**
+     * Unique identifier for this component instance,
+     * used for finding and tracking components
+     */
     guid: string = "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
+     */
     sourceId?: SourceIdentifier;
-    // transform: Object3D = nullObject;
 
-    /** called on a component with a map of old to new guids (e.g. when instantiate generated new guids and e.g. timeline track bindings needs to remape them) */
+    /**
+     * Called when this component needs to remap guids after an instantiate operation.
+     * @param guidsMap Mapping from old guids to newly generated guids
+     */
     resolveGuids?(guidsMap: GuidsMap): void;
 
-    /** 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 = true;
     }
-    /** called when you decorate fields with the @validate() decorator
-     * @param prop the name of the field that was changed
+    
+    /**
+     * Called when a field decorated with @validate() is modified.
+     * @param prop The name of the field that was changed
      */
     onValidate?(prop?: string): void;
 
-    /** Called for all scripts when the context gets paused or unpaused */
+    /**
+     * Called when the context's pause state changes.
+     * @param isPaused Whether the context is currently paused
+     * @param wasPaused The previous pause state
+     */
     onPausedChanged?(isPaused: boolean, wasPaused: boolean): void;
 
-    /** called at the beginning of a frame (once per component) */
+    /**
+     * Called once at the beginning of the first frame after the component is enabled.
+     * Use for initialization that requires other components to be awake.
+     */
     start?(): void;
-    /** first callback in a frame (called every frame when implemented) */
+    
+    /**
+     * Called at the beginning of each frame before regular updates.
+     * Use for logic that needs to run before standard update callbacks.
+     */
     earlyUpdate?(): void;
-    /** regular callback in a frame (called every frame when implemented) */
+    
+    /**
+     * Called once per frame during the main update loop.
+     * The primary location for frame-based game logic.
+     */
     update?(): void;
-    /** late callback in a frame (called every frame when implemented) */
+    
+    /**
+     * Called after all update functions have been called.
+     * Use for calculations that depend on other components being updated first.
+     */
     lateUpdate?(): void;
-    /** called before the scene gets rendered in the main update loop */
+    
+    /**
+     * Called immediately before the scene is rendered.
+     * @param frame Current XRFrame if in an XR session, null otherwise
+     */
     onBeforeRender?(frame: XRFrame | null): void;
-    /** called after the scene was rendered */
+    
+    /**
+     * Called after the scene has been rendered.
+     * Use for post-processing or UI updates that should happen after rendering
+     */
     onAfterRender?(): void;
 
+    /**
+     * Called when this component's collider begins colliding with another collider.
+     * @param col Information about the collision that occurred
+     */
     onCollisionEnter?(col: Collision);
+    
+    /**
+     * Called when this component's collider stops colliding with another collider.
+     * @param col Information about the collision that ended
+     */
     onCollisionExit?(col: Collision);
+    
+    /**
+     * Called each frame while this component's collider is colliding with another collider
+     * @param col Information about the ongoing collision
+     */
     onCollisionStay?(col: Collision);
 
+    /**
+     * Called when this component's trigger collider is entered by another collider
+     * @param col The collider that entered this trigger
+     */
     onTriggerEnter?(col: ICollider);
+    
+    /**
+     * Called each frame while another collider is inside this component's trigger collider
+     * @param col The collider that is inside this trigger
+     */
     onTriggerStay?(col: ICollider);
+    
+    /**
+     * Called when another collider exits this component's trigger collider
+     * @param col The collider that exited this trigger
+     */
     onTriggerExit?(col: ICollider);
 
-
-    /** Optional callback, you can implement this to only get callbacks for VR or AR sessions if necessary. 
-     * @returns true if the mode is supported (if false the mode is not supported by this component and it will not receive XR callbacks for this mode)
-    */
+    /**
+     * Determines if this component supports a specific XR mode
+     * @param mode The XR session mode to check support for
+     * @returns True if the component supports the specified mode
+     */
     supportsXR?(mode: XRSessionMode): boolean;
-    /** Called before the XR session is requested. Use this callback if you want to modify the session init features */
+    
+    /**
+     * Called before an XR session is requested
+     * Use to modify session initialization parameters
+     * @param mode The XR session mode being requested
+     * @param args The session initialization parameters that can be modified
+     */
     onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
-    /** Callback when this component joins a xr session (or becomes active in a running XR session) */
+    
+    /**
+     * Called when this component joins an XR session or becomes active in a running session
+     * @param args Event data for the XR session
+     */
     onEnterXR?(args: NeedleXREventArgs): void;
-    /** Callback when a xr session updates (while it is still active in XR session) */
+    
+    /**
+     * Called each frame while this component is active in an XR session
+     * @param args Event data for the current XR frame
+     */
     onUpdateXR?(args: NeedleXREventArgs): void;
-    /** Callback when this component exists a xr session (or when it becomes inactive in a running XR session) */
+    
+    /**
+     * Called when this component exits an XR session or becomes inactive during a session
+     * @param args Event data for the XR session
+     */
     onLeaveXR?(args: NeedleXREventArgs): void;
-    /** Callback when a controller is connected/added while in a XR session  
-     * OR when the component joins a running XR session that has already connected controllers  
-     * OR when the component becomes active during a running XR session that has already connected controllers */
+    
+    /**
+     * Called when an XR controller is connected or when this component becomes active
+     * in a session with existing controllers
+     * @param args Event data for the controller that was added
+     */
     onXRControllerAdded?(args: NeedleXRControllerEventArgs): void;
-    /** callback when a controller is removed while in a XR session   
-     * OR when the component becomes inactive during a running XR session
-    */
+    
+    /**
+     * Called when an XR controller is disconnected or when this component becomes inactive
+     * during a session with controllers
+     * @param args Event data for the controller that was removed
+     */
     onXRControllerRemoved?(args: NeedleXRControllerEventArgs): void;
 
-
-    /* IPointerEventReceiver */
-    /* @inheritdoc */
+    /**
+     * Called when a pointer enters this component's GameObject
+     * @param args Data about the pointer event
+     */
     onPointerEnter?(args: PointerEventData);
+    
+    /**
+     * Called when a pointer moves while over this component's GameObject
+     * @param args Data about the pointer event
+     */
     onPointerMove?(args: PointerEventData);
+    
+    /**
+     * Called when a pointer exits this component's GameObject
+     * @param args Data about the pointer event
+     */
     onPointerExit?(args: PointerEventData);
+    
+    /**
+     * Called when a pointer button is pressed while over this component's GameObject
+     * @param args Data about the pointer event
+     */
     onPointerDown?(args: PointerEventData);
+    
+    /**
+     * Called when a pointer button is released while over this component's GameObject
+     * @param args Data about the pointer event
+     */
     onPointerUp?(args: PointerEventData);
+    
+    /**
+     * Called when a pointer completes a click interaction with this component's GameObject
+     * @param args Data about the pointer event
+     */
     onPointerClick?(args: PointerEventData);
 
-
-    /** 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;
+     *   }
      * }
      * ```
      */
     startCoroutine(routine: Generator, evt: FrameEvent = FrameEvent.Update): Generator {
         return this.context.registerCoroutineUpdate(this, routine, evt);
     }
+    
     /**
-     * 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(routine: Generator, evt: FrameEvent = FrameEvent.Update): void {
         this.context.unregisterCoroutineUpdate(routine, evt);
     }
 
-    /** @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
+     */
     public get destroyed(): boolean {
         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
      */
     public destroy() {
         if (this.__destroyed) return;
         this.__internalDestroy();
     }
 
-
-
     /** @internal */
     protected __didAwake: boolean = false;
 
@@ -589,7 +989,6 @@ export abstract class Component implements IComponent, EventTarget,
     /** @internal */
     get __internalDidAwakeAndStart() { return this.__didAwake && this.__didStart; }
 
-
     /** @internal */
     constructor(init?: ComponentInit<Component>) {
         this.__didAwake = false;
@@ -611,6 +1010,11 @@ export abstract class Component implements IComponent, EventTarget,
         return this;
     }
 
+    /**
+     * Initializes component properties from an initialization object
+     * @param init Object with properties to copy to this component
+     * @internal
+     */
     _internalInit(init?: ComponentInit<this>) {
         if (typeof init === "object") {
             for (const key of Object.keys(init)) {
@@ -690,7 +1094,10 @@ export abstract class Component implements IComponent, EventTarget,
         destroyComponentInstance(this as any);
     }
 
-
+    /**
+     * Controls whether this component is enabled
+     * Disabled components don't receive lifecycle callbacks
+     */
     get enabled(): boolean {
         return typeof this.__isEnabled === "boolean" ? this.__isEnabled : true; // if it has no enabled field it is always enabled
     }
@@ -720,85 +1127,154 @@ export abstract class Component implements IComponent, EventTarget,
         }
     }
 
+    /**
+     * Gets the position of this component's GameObject in world space
+     */
     get worldPosition(): Vector3 {
         return threeutils.getWorldPosition(this.gameObject);
     }
 
+    /**
+     * Sets the position of this component's GameObject in world space
+     * @param val The world position vector to set
+     */
     set worldPosition(val: Vector3) {
         threeutils.setWorldPosition(this.gameObject, val);
     }
 
+    /**
+     * 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(x: number, y: number, z: number) {
         threeutils.setWorldPositionXYZ(this.gameObject, x, y, z);
     }
 
-
+    /**
+     * Gets the rotation of this component's GameObject in world space as a quaternion
+     */
     get worldQuaternion(): Quaternion {
         return threeutils.getWorldQuaternion(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(val: Quaternion) {
         threeutils.setWorldQuaternion(this.gameObject, val);
     }
+    
+    /**
+     * 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(x: number, y: number, z: number, w: number) {
         threeutils.setWorldQuaternionXYZW(this.gameObject, x, y, z, w);
     }
 
-    // world euler (in radians)
+    /**
+     * Gets the rotation of this component's GameObject in world space as Euler angles (in radians)
+     */
     get worldEuler(): Euler {
         return threeutils.getWorldEuler(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(val: Euler) {
         threeutils.setWorldEuler(this.gameObject, val);
     }
 
-    // returns rotation in degrees
+    /**
+     * Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)
+     */
     get worldRotation(): Vector3 {
-        return this.gameObject.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(val: Vector3) {
         this.setWorldRotation(val.x, val.y, val.z, true);
     }
 
+    /**
+     * 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(x: number, y: number, z: number, degrees: boolean = true) {
         threeutils.setWorldRotationXYZ(this.gameObject, x, y, z, degrees);
     }
 
     private static _forward: Vector3 = new Vector3();
-    /** Forward (0,0,-1) vector in world space */
+    /**
+     * Gets the forward direction vector (0,0,-1) of this component's GameObject in world space
+     */
     public get forward(): Vector3 {
         return Component._forward.set(0, 0, -1).applyQuaternion(this.worldQuaternion);
     }
     private static _right: Vector3 = new Vector3();
-    /** Right (1,0,0) vector in world space */
+    /**
+     * Gets the right direction vector (1,0,0) of this component's GameObject in world space
+     */
     public get right(): Vector3 {
         return Component._right.set(1, 0, 0).applyQuaternion(this.worldQuaternion);
     }
     private static _up: Vector3 = new Vector3();
-    /** Up (0,1,0) vector in world space */
+    /**
+     * Gets the up direction vector (0,1,0) of this component's GameObject in world space
+     */
     public get up(): Vector3 {
         return Component._up.set(0, 1, 0).applyQuaternion(this.worldQuaternion);
     }
 
-
-
     // EventTarget implementation:
 
+    /** 
+     * Storage for event listeners registered to this component
+     * @private
+     */
     private _eventListeners = new Map<string, EventListener[]>();
 
+    /**
+     * 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 extends Event>(type: string, listener: (evt: T) => any) {
         this._eventListeners[type] = this._eventListeners[type] || [];
         this._eventListeners[type].push(listener);
     }
 
+    /**
+     * 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 extends Event>(type: string, listener: (arg: T) => any) {
         if (!this._eventListeners[type]) return;
         const index = this._eventListeners[type].indexOf(listener);
         if (index >= 0) this._eventListeners[type].splice(index, 1);
     }
 
+    /**
+     * Dispatches an event to all registered listeners
+     * @param evt The event object to dispatch
+     * @returns Always returns false (standard implementation of EventTarget)
+     */
     dispatchEvent(evt: Event): boolean {
         if (!evt || !this._eventListeners[evt.type]) return false;
         const listeners = this._eventListeners[evt.type];