@needle-tools/engine 4.4.1 → 4.4.2

package/src/engine-components/Component.ts

@@ -1,1294 +1,1294 @@
-import { Euler, Object3D, Quaternion, Scene, Vector3 } from "three";
-
-import { isDevEnvironment } from "../engine/debug/index.js";
-import { type AssetReference } from "../engine/engine_addressables.js";
-import { addComponent, destroyComponentInstance, findObjectOfType, findObjectsOfType, getComponent, getComponentInChildren, getComponentInParent, getComponents, getComponentsInChildren, getComponentsInParent, getOrAddComponent, removeComponent } from "../engine/engine_components.js";
-import { activeInHierarchyFieldName } from "../engine/engine_constants.js";
-import { destroy, findByGuid, foreachComponent, type IInstantiateOptions, instantiate, isActiveInHierarchy, isActiveSelf, isDestroyed, isUsingInstancing, markAsInstancedRendered, setActive } from "../engine/engine_gameobject.js";
-import * as main from "../engine/engine_mainloop_utils.js";
-import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/engine_networking_instantiate.js";
-import { Context, FrameEvent } from "../engine/engine_setup.js";
-import * as threeutils from "../engine/engine_three_utils.js";
-import type { Collision, ComponentInit, Constructor, ConstructorConcrete, GuidsMap, ICollider, IComponent, IGameObject, SourceIdentifier } from "../engine/engine_types.js";
-import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
-import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
-
-
-// export interface ISerializationCallbackReceiver {
-//     onBeforeSerialize?(): object | void;
-//     onAfterSerialize?();
-//     onBeforeDeserialize?(data?: any);
-//     onAfterDeserialize?();
-//     onDeserialize?(key: string, value: any): any | void;
-// }
-
-/**
- * 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
- * GameObject.setActive(target, true);
- * ```
- */
-export abstract class GameObject extends Object3D implements Object3D, IGameObject {
-
-    /** 
-     * 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 {@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 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;
-
-    /**
-     * 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);
-
-        // TODO: do we still need this?:
-        main.updateIsActive(go);
-        if (active && processStart)
-            main.processStart(Context.Current, go);
-    }
-
-    /**
-     * 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);
-    }
-
-    /**
-     * 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); }
-
-    /**
-     * 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 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.)
-     * @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> {
-        if ('isAssetReference' in instance) {
-            return instantiate(instance as AssetReference, opts);
-        }
-        return instantiate(instance as GameObject | Object3D, opts) as GameObject;
-    }
-
-    /**
-     * 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;
-        context = context ?? Context.Current;
-        syncDestroy(go as any, context.connection, recursive);
-    }
-
-    /**
-     * 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);
-    }
-
-    /**
-     * 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;
-        if (instance === parent) {
-            console.warn("Can not add object to self", instance);
-            return;
-        }
-        if (!context) {
-            context = Context.Current;
-        }
-        parent.add(instance);
-        setActive(instance, true);
-        main.updateIsActive(instance);
-        if (context) {
-            GameObject.foreachComponent(instance, (comp: Component) => {
-                main.addScriptToArrays(comp, context!);
-                if (comp.__internalDidAwakeAndStart) return;
-                if (context!.new_script_start.includes(comp) === false) {
-                    context!.new_script_start.push(comp as Component);
-                }
-            }, true);
-        }
-        else {
-            console.warn("Missing context");
-        }
-    }
-
-    /**
-     * 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;
-        instance.parent?.remove(instance);
-        setActive(instance, false);
-        main.updateIsActive(instance);
-        GameObject.foreachComponent(instance, (comp) => {
-            main.processRemoveFromScene(comp);
-        }, true);
-    }
-
-    /**
-     * 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 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;
-        this.foreachComponent(go, c => {
-            const fn = c[functionName];
-            if (fn && typeof fn === "function") {
-                fn?.call(c, ...args)
-            }
-        }, children);
-    }
-
-    /** @deprecated use `addComponent` */
-    // eslint-disable-next-line deprecation/deprecation
-    public static addNewComponent<T extends IComponent>(go: IGameObject | Object3D, type: T | ConstructorConcrete<T>, init?: ComponentInit<T>, callAwake: boolean = true): T {
-        return addComponent(go, type, init, { callAwake });
-    }
-
-    /**
-     * 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 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
-     * @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
-     * @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
-        // not ideal, but I dont know a good/sane way to do this otherwise
-        // const res = TypeStore.get(typeName);
-        // if(res) typeName = res;
-        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 [];
-        const newList = [...componentsList];
-        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)) {
-            for (let i = 0; i < list.length; i++) {
-                yield list[i];
-            }
-        }
-    }
-}
-
-
-
-/** 
- * Needle Engine component base class. Component's are the main building blocks of the Needle Engine.    
- * Derive from {@link Behaviour} to implement your own using the provided lifecycle methods.    
- * Components can be added to any {@link Object3D} using {@link addComponent} or {@link GameObject.addComponent}. 
- * 
- * The most common lifecycle methods are {@link update}, {@link awake}, {@link start}, {@link onEnable}, {@link onDisable} and {@link onDestroy}.   
- * 
- * XR specific callbacks include {@link onEnterXR}, {@link onLeaveXR}, {@link onUpdateXR}, {@link onXRControllerAdded} and {@link onXRControllerRemoved}.    
- * 
- * To receive pointer events implement {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
- * 
- * @example
- * ```typescript
- * import { Behaviour } from "@needle-tools/engine";
- * export class MyComponent extends Behaviour {
- *  start() {
- *     console.log("Hello World");
- *  }
- *  update() {
- *    console.log("Frame", this.context.time.frame);
- *  }
- * }
- * ```
- * 
- * @group Components
- */
-export abstract class Component implements IComponent, EventTarget,
-    Partial<INeedleXRSessionEventReceiver>,
-    Partial<IPointerEventHandler>
-{
-    /** 
-     * Indicates whether this object is a component
-     * @internal 
-     */
-    get isComponent(): boolean { return true; }
-
-    private __context: Context | undefined;
-    
-    /**
-     * 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 accessor for the current scene from the context
-     * @returns The scene this component belongs to
-     */
-    get scene(): Scene { return this.context.scene; }
-
-    /**
-     * 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;
-    }
-
-    /**
-     * 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;
-        }
-        return this.gameObject?.userData.name;
-    }
-    private __name?: string;
-    set name(str: string) {
-        if (this.gameObject) {
-            if (!this.gameObject.userData) this.gameObject.userData = {}
-            this.gameObject.userData.name = str;
-            this.__name = str;
-        }
-        else {
-            this.__name = str;
-        }
-    }
-    
-    /**
-     * 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;
-    }
-    set tag(str: string) {
-        if (this.gameObject) {
-            if (!this.gameObject.userData) this.gameObject.userData = {}
-            this.gameObject.userData.tag = str;
-        }
-    }
-    
-    /**
-     * 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;
-    }
-    set static(value: boolean) {
-        if (this.gameObject) {
-            if (!this.gameObject.userData) this.gameObject.userData = {}
-            this.gameObject.userData.static = value;
-        }
-    }
-    // get hideFlags(): HideFlags {
-    //     return this.gameObject?.hideFlags;
-    // }
-
-    /**
-     * 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;
-        if (!this.__isActiveInHierarchy) return false;
-        // let go = this.gameObject;
-        // do {
-        //     // console.log(go.name, go.visible)
-        //     if (!go.visible) return false;
-        //     go = go.parent as GameObject;
-        // }
-        // while (go);
-        return true;
-    }
-
-    private get __isActive(): boolean {
-        return this.gameObject.visible;
-    }
-    
-    private get __isActiveInHierarchy(): boolean {
-        if (!this.gameObject) return false;
-        const res = this.gameObject[activeInHierarchyFieldName];
-        if (res === undefined) return true;
-        return res;
-    }
-
-    private set __isActiveInHierarchy(val: boolean) {
-        if (!this.gameObject) return;
-        this.gameObject[activeInHierarchyFieldName] = val;
-    }
-
-    /**
-     * Reference to the GameObject this component is attached to
-     * This is a three.js Object3D with additional GameObject functionality
-     */
-    gameObject!: GameObject;
-    
-    /**
-     * Unique identifier for this component instance,
-     * used for finding and tracking components
-     */
-    guid: string = "invalid";
-    
-    /**
-     * Identifier for the source asset that created this component.
-     * For example, URL to the glTF file this component was loaded from
-     */
-    sourceId?: SourceIdentifier;
-
-    /**
-     * 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.
-     * This is the first lifecycle callback to be invoked
-     */
-    awake() { }
-    
-    /**
-     * 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 becomes disabled or inactive in the hierarchy.
-     * Invoked when the component or any parent GameObject becomes invisible
-     */
-    onDisable() { }
-    
-    /**
-     * Called when the component is destroyed.
-     * Use for cleanup operations like removing event listeners
-     */
-    onDestroy() {
-        this.__destroyed = true;
-    }
-    
-    /**
-     * Called when a field decorated with @validate() is modified.
-     * @param prop The name of the field that was changed
-     */
-    onValidate?(prop?: string): void;
-
-    /**
-     * 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 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;
-    
-    /**
-     * Called at the beginning of each frame before regular updates.
-     * Use for logic that needs to run before standard update callbacks.
-     */
-    earlyUpdate?(): void;
-    
-    /**
-     * Called once per frame during the main update loop.
-     * The primary location for frame-based game logic.
-     */
-    update?(): void;
-    
-    /**
-     * Called after all update functions have been called.
-     * Use for calculations that depend on other components being updated first.
-     */
-    lateUpdate?(): void;
-    
-    /**
-     * 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 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);
-
-    /**
-     * 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 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;
-    
-    /**
-     * 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;
-    
-    /**
-     * 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;
-    
-    /**
-     * 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;
-    
-    /**
-     * 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;
-    
-    /**
-     * 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;
-
-    /**
-     * 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 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());
-     * }
-     * 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;
-     *   }
-     * }
-     * ```
-     */
-    startCoroutine(routine: Generator, evt: FrameEvent = FrameEvent.Update): Generator {
-        return this.context.registerCoroutineUpdate(this, routine, evt);
-    }
-    
-    /**
-     * 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);
-    }
-
-    /**
-     * 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 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;
-
-    /** @internal */
-    private __didStart: boolean = false;
-
-    /** @internal */
-    protected __didEnable: boolean = false;
-
-    /** @internal */
-    protected __isEnabled: boolean | undefined = undefined;
-
-    /** @internal */
-    private __destroyed: boolean = false;
-
-    /** @internal */
-    get __internalDidAwakeAndStart() { return this.__didAwake && this.__didStart; }
-
-    /** @internal */
-    constructor(init?: ComponentInit<Component>) {
-        this.__didAwake = false;
-        this.__didStart = false;
-        this.__didEnable = false;
-        this.__isEnabled = undefined;
-        this.__destroyed = false;
-        this._internalInit(init as ComponentInit<this>);
-    }
-
-    /** @internal */
-    __internalNewInstanceCreated(init?: ComponentInit<this>): this {
-        this.__didAwake = false;
-        this.__didStart = false;
-        this.__didEnable = false;
-        this.__isEnabled = undefined;
-        this.__destroyed = false;
-        this._internalInit(init);
-        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)) {
-                const value = init[key];
-                // we don't want to allow overriding functions via init
-                if (typeof value === "function") continue;
-                (this as any)[key] = value;
-            }
-        }
-    }
-
-    /** @internal */
-    __internalAwake() {
-        if (this.__didAwake) return;
-        this.__didAwake = true;
-        this.awake();
-    }
-
-
-    /** @internal */
-    __internalStart() {
-        if (this.__didStart) return;
-        this.__didStart = true;
-        if (this.start) this.start();
-    }
-
-
-    /** @internal */
-    __internalEnable(isAddingToScene?: boolean): boolean {
-        if (this.__destroyed) {
-            if (isDevEnvironment()) {
-                console.warn("[Needle Engine Dev] Trying to enable destroyed component");
-            }
-            return false;
-        }
-        // Don't change enable before awake
-        // But a user can change enable during awake
-        if (!this.__didAwake) return false;
-        if (this.__didEnable) {
-            // We dont want to change the enable state if we are adding to scene
-            // But we want to change the state when e.g. a user changes the enable state during awake
-            if (isAddingToScene !== true)
-                this.__isEnabled = true;
-            return false;
-        }
-        // console.trace("INTERNAL ENABLE");
-        this.__didEnable = true;
-        this.__isEnabled = true;
-        this.onEnable();
-        return true;
-    }
-
-    /** @internal */
-    __internalDisable(isRemovingFromScene?: boolean) {
-        // Don't change enable before awake
-        // But a user can change enable during awake
-        if (!this.__didAwake) return;
-        if (!this.__didEnable) {
-            // We dont want to change the enable state if we are removing from a scene
-            if (isRemovingFromScene !== true)
-                this.__isEnabled = false;
-            return;
-        }
-        this.__didEnable = false;
-        this.__isEnabled = false;
-        this.onDisable();
-    }
-
-    /** @internal */
-    __internalDestroy() {
-        if (this.__destroyed) return;
-        this.__destroyed = true;
-        if (this.__didAwake) {
-            this.onDestroy?.call(this);
-            this.dispatchEvent(new CustomEvent("destroyed", { detail: this }));
-        }
-        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
-    }
-    set enabled(val: boolean) {
-        if (this.__destroyed) {
-            if (isDevEnvironment()) {
-                console.warn(`[Needle Engine Dev] Trying to ${val ? "enable" : "disable"} destroyed component`);
-            }
-            return;
-        }
-        // when called from animationclip we receive numbers
-        // due to interpolation they can be anything between 0 and 1
-        if (typeof val === "number") {
-            if (val >= 0.5) val = true;
-            else val = false;
-        }
-
-        // need to check here because codegen is calling this before everything is setup
-        if (!this.__didAwake) {
-            this.__isEnabled = val;
-            return;
-        }
-        if (val) {
-            this.__internalEnable();
-        } else {
-            this.__internalDisable();
-        }
-    }
-
-    /**
-     * Gets the position of this component's GameObject in world space.    
-     * Note: This is equivalent to calling `this.gameObject.worldPosition`
-     */
-    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
-     * Note: This is equivalent to calling `this.gameObject.worldQuaternion`
-     */
-    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);
-    }
-
-    /**
-     * Gets the rotation of this component's GameObject in world space as Euler angles (in radians)
-     */
-    get worldEuler(): Euler {
-        return threeutils.getWorldEuler(this.gameObject);
-    }
-
-    /**
-     * 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);
-    }
-
-    /**
-     * Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)  
-     * Note: This is equivalent to calling `this.gameObject.worldRotation`
-     */
-    get worldRotation(): Vector3 {
-        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();
-    /**
-     * 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();
-    /**
-     * 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();
-    /**
-     * 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];
-        for (let i = 0; i < listeners.length; i++) {
-            listeners[i](evt);
-        }
-
-        return false;
-    }
-}
-
-// For legacy reasons we need to export this as well 
-// (and we don't use extend to inherit the component docs)
-export { Component as Behaviour };
+import { Euler, Object3D, Quaternion, Scene, Vector3 } from "three";
+
+import { isDevEnvironment } from "../engine/debug/index.js";
+import { type AssetReference } from "../engine/engine_addressables.js";
+import { addComponent, destroyComponentInstance, findObjectOfType, findObjectsOfType, getComponent, getComponentInChildren, getComponentInParent, getComponents, getComponentsInChildren, getComponentsInParent, getOrAddComponent, removeComponent } from "../engine/engine_components.js";
+import { activeInHierarchyFieldName } from "../engine/engine_constants.js";
+import { destroy, findByGuid, foreachComponent, type IInstantiateOptions, instantiate, isActiveInHierarchy, isActiveSelf, isDestroyed, isUsingInstancing, markAsInstancedRendered, setActive } from "../engine/engine_gameobject.js";
+import * as main from "../engine/engine_mainloop_utils.js";
+import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/engine_networking_instantiate.js";
+import { Context, FrameEvent } from "../engine/engine_setup.js";
+import * as threeutils from "../engine/engine_three_utils.js";
+import type { Collision, ComponentInit, Constructor, ConstructorConcrete, GuidsMap, ICollider, IComponent, IGameObject, SourceIdentifier } from "../engine/engine_types.js";
+import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
+import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
+
+
+// export interface ISerializationCallbackReceiver {
+//     onBeforeSerialize?(): object | void;
+//     onAfterSerialize?();
+//     onBeforeDeserialize?(data?: any);
+//     onAfterDeserialize?();
+//     onDeserialize?(key: string, value: any): any | void;
+// }
+
+/**
+ * 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
+ * GameObject.setActive(target, true);
+ * ```
+ */
+export abstract class GameObject extends Object3D implements Object3D, IGameObject {
+
+    /** 
+     * 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 {@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 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;
+
+    /**
+     * 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);
+
+        // TODO: do we still need this?:
+        main.updateIsActive(go);
+        if (active && processStart)
+            main.processStart(Context.Current, go);
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * 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); }
+
+    /**
+     * 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 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.)
+     * @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> {
+        if ('isAssetReference' in instance) {
+            return instantiate(instance as AssetReference, opts);
+        }
+        return instantiate(instance as GameObject | Object3D, opts) as GameObject;
+    }
+
+    /**
+     * 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;
+        context = context ?? Context.Current;
+        syncDestroy(go as any, context.connection, recursive);
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * 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;
+        if (instance === parent) {
+            console.warn("Can not add object to self", instance);
+            return;
+        }
+        if (!context) {
+            context = Context.Current;
+        }
+        parent.add(instance);
+        setActive(instance, true);
+        main.updateIsActive(instance);
+        if (context) {
+            GameObject.foreachComponent(instance, (comp: Component) => {
+                main.addScriptToArrays(comp, context!);
+                if (comp.__internalDidAwakeAndStart) return;
+                if (context!.new_script_start.includes(comp) === false) {
+                    context!.new_script_start.push(comp as Component);
+                }
+            }, true);
+        }
+        else {
+            console.warn("Missing context");
+        }
+    }
+
+    /**
+     * 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;
+        instance.parent?.remove(instance);
+        setActive(instance, false);
+        main.updateIsActive(instance);
+        GameObject.foreachComponent(instance, (comp) => {
+            main.processRemoveFromScene(comp);
+        }, true);
+    }
+
+    /**
+     * 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 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;
+        this.foreachComponent(go, c => {
+            const fn = c[functionName];
+            if (fn && typeof fn === "function") {
+                fn?.call(c, ...args)
+            }
+        }, children);
+    }
+
+    /** @deprecated use `addComponent` */
+    // eslint-disable-next-line deprecation/deprecation
+    public static addNewComponent<T extends IComponent>(go: IGameObject | Object3D, type: T | ConstructorConcrete<T>, init?: ComponentInit<T>, callAwake: boolean = true): T {
+        return addComponent(go, type, init, { callAwake });
+    }
+
+    /**
+     * 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 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
+     * @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
+     * @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
+        // not ideal, but I dont know a good/sane way to do this otherwise
+        // const res = TypeStore.get(typeName);
+        // if(res) typeName = res;
+        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 [];
+        const newList = [...componentsList];
+        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)) {
+            for (let i = 0; i < list.length; i++) {
+                yield list[i];
+            }
+        }
+    }
+}
+
+
+
+/** 
+ * Needle Engine component base class. Component's are the main building blocks of the Needle Engine.    
+ * Derive from {@link Behaviour} to implement your own using the provided lifecycle methods.    
+ * Components can be added to any {@link Object3D} using {@link addComponent} or {@link GameObject.addComponent}. 
+ * 
+ * The most common lifecycle methods are {@link update}, {@link awake}, {@link start}, {@link onEnable}, {@link onDisable} and {@link onDestroy}.   
+ * 
+ * XR specific callbacks include {@link onEnterXR}, {@link onLeaveXR}, {@link onUpdateXR}, {@link onXRControllerAdded} and {@link onXRControllerRemoved}.    
+ * 
+ * To receive pointer events implement {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
+ * 
+ * @example
+ * ```typescript
+ * import { Behaviour } from "@needle-tools/engine";
+ * export class MyComponent extends Behaviour {
+ *  start() {
+ *     console.log("Hello World");
+ *  }
+ *  update() {
+ *    console.log("Frame", this.context.time.frame);
+ *  }
+ * }
+ * ```
+ * 
+ * @group Components
+ */
+export abstract class Component implements IComponent, EventTarget,
+    Partial<INeedleXRSessionEventReceiver>,
+    Partial<IPointerEventHandler>
+{
+    /** 
+     * Indicates whether this object is a component
+     * @internal 
+     */
+    get isComponent(): boolean { return true; }
+
+    private __context: Context | undefined;
+    
+    /**
+     * 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 accessor for the current scene from the context
+     * @returns The scene this component belongs to
+     */
+    get scene(): Scene { return this.context.scene; }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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;
+        }
+        return this.gameObject?.userData.name;
+    }
+    private __name?: string;
+    set name(str: string) {
+        if (this.gameObject) {
+            if (!this.gameObject.userData) this.gameObject.userData = {}
+            this.gameObject.userData.name = str;
+            this.__name = str;
+        }
+        else {
+            this.__name = str;
+        }
+    }
+    
+    /**
+     * 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;
+    }
+    set tag(str: string) {
+        if (this.gameObject) {
+            if (!this.gameObject.userData) this.gameObject.userData = {}
+            this.gameObject.userData.tag = str;
+        }
+    }
+    
+    /**
+     * 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;
+    }
+    set static(value: boolean) {
+        if (this.gameObject) {
+            if (!this.gameObject.userData) this.gameObject.userData = {}
+            this.gameObject.userData.static = value;
+        }
+    }
+    // get hideFlags(): HideFlags {
+    //     return this.gameObject?.hideFlags;
+    // }
+
+    /**
+     * 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;
+        if (!this.__isActiveInHierarchy) return false;
+        // let go = this.gameObject;
+        // do {
+        //     // console.log(go.name, go.visible)
+        //     if (!go.visible) return false;
+        //     go = go.parent as GameObject;
+        // }
+        // while (go);
+        return true;
+    }
+
+    private get __isActive(): boolean {
+        return this.gameObject.visible;
+    }
+    
+    private get __isActiveInHierarchy(): boolean {
+        if (!this.gameObject) return false;
+        const res = this.gameObject[activeInHierarchyFieldName];
+        if (res === undefined) return true;
+        return res;
+    }
+
+    private set __isActiveInHierarchy(val: boolean) {
+        if (!this.gameObject) return;
+        this.gameObject[activeInHierarchyFieldName] = val;
+    }
+
+    /**
+     * Reference to the GameObject this component is attached to
+     * This is a three.js Object3D with additional GameObject functionality
+     */
+    gameObject!: GameObject;
+    
+    /**
+     * Unique identifier for this component instance,
+     * used for finding and tracking components
+     */
+    guid: string = "invalid";
+    
+    /**
+     * Identifier for the source asset that created this component.
+     * For example, URL to the glTF file this component was loaded from
+     */
+    sourceId?: SourceIdentifier;
+
+    /**
+     * 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.
+     * This is the first lifecycle callback to be invoked
+     */
+    awake() { }
+    
+    /**
+     * 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 becomes disabled or inactive in the hierarchy.
+     * Invoked when the component or any parent GameObject becomes invisible
+     */
+    onDisable() { }
+    
+    /**
+     * Called when the component is destroyed.
+     * Use for cleanup operations like removing event listeners
+     */
+    onDestroy() {
+        this.__destroyed = true;
+    }
+    
+    /**
+     * Called when a field decorated with @validate() is modified.
+     * @param prop The name of the field that was changed
+     */
+    onValidate?(prop?: string): void;
+
+    /**
+     * 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 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;
+    
+    /**
+     * Called at the beginning of each frame before regular updates.
+     * Use for logic that needs to run before standard update callbacks.
+     */
+    earlyUpdate?(): void;
+    
+    /**
+     * Called once per frame during the main update loop.
+     * The primary location for frame-based game logic.
+     */
+    update?(): void;
+    
+    /**
+     * Called after all update functions have been called.
+     * Use for calculations that depend on other components being updated first.
+     */
+    lateUpdate?(): void;
+    
+    /**
+     * 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 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);
+
+    /**
+     * 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 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;
+    
+    /**
+     * 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;
+    
+    /**
+     * 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;
+    
+    /**
+     * 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;
+    
+    /**
+     * 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;
+    
+    /**
+     * 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;
+
+    /**
+     * 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 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());
+     * }
+     * 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;
+     *   }
+     * }
+     * ```
+     */
+    startCoroutine(routine: Generator, evt: FrameEvent = FrameEvent.Update): Generator {
+        return this.context.registerCoroutineUpdate(this, routine, evt);
+    }
+    
+    /**
+     * 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);
+    }
+
+    /**
+     * 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 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;
+
+    /** @internal */
+    private __didStart: boolean = false;
+
+    /** @internal */
+    protected __didEnable: boolean = false;
+
+    /** @internal */
+    protected __isEnabled: boolean | undefined = undefined;
+
+    /** @internal */
+    private __destroyed: boolean = false;
+
+    /** @internal */
+    get __internalDidAwakeAndStart() { return this.__didAwake && this.__didStart; }
+
+    /** @internal */
+    constructor(init?: ComponentInit<Component>) {
+        this.__didAwake = false;
+        this.__didStart = false;
+        this.__didEnable = false;
+        this.__isEnabled = undefined;
+        this.__destroyed = false;
+        this._internalInit(init as ComponentInit<this>);
+    }
+
+    /** @internal */
+    __internalNewInstanceCreated(init?: ComponentInit<this>): this {
+        this.__didAwake = false;
+        this.__didStart = false;
+        this.__didEnable = false;
+        this.__isEnabled = undefined;
+        this.__destroyed = false;
+        this._internalInit(init);
+        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)) {
+                const value = init[key];
+                // we don't want to allow overriding functions via init
+                if (typeof value === "function") continue;
+                (this as any)[key] = value;
+            }
+        }
+    }
+
+    /** @internal */
+    __internalAwake() {
+        if (this.__didAwake) return;
+        this.__didAwake = true;
+        this.awake();
+    }
+
+
+    /** @internal */
+    __internalStart() {
+        if (this.__didStart) return;
+        this.__didStart = true;
+        if (this.start) this.start();
+    }
+
+
+    /** @internal */
+    __internalEnable(isAddingToScene?: boolean): boolean {
+        if (this.__destroyed) {
+            if (isDevEnvironment()) {
+                console.warn("[Needle Engine Dev] Trying to enable destroyed component");
+            }
+            return false;
+        }
+        // Don't change enable before awake
+        // But a user can change enable during awake
+        if (!this.__didAwake) return false;
+        if (this.__didEnable) {
+            // We dont want to change the enable state if we are adding to scene
+            // But we want to change the state when e.g. a user changes the enable state during awake
+            if (isAddingToScene !== true)
+                this.__isEnabled = true;
+            return false;
+        }
+        // console.trace("INTERNAL ENABLE");
+        this.__didEnable = true;
+        this.__isEnabled = true;
+        this.onEnable();
+        return true;
+    }
+
+    /** @internal */
+    __internalDisable(isRemovingFromScene?: boolean) {
+        // Don't change enable before awake
+        // But a user can change enable during awake
+        if (!this.__didAwake) return;
+        if (!this.__didEnable) {
+            // We dont want to change the enable state if we are removing from a scene
+            if (isRemovingFromScene !== true)
+                this.__isEnabled = false;
+            return;
+        }
+        this.__didEnable = false;
+        this.__isEnabled = false;
+        this.onDisable();
+    }
+
+    /** @internal */
+    __internalDestroy() {
+        if (this.__destroyed) return;
+        this.__destroyed = true;
+        if (this.__didAwake) {
+            this.onDestroy?.call(this);
+            this.dispatchEvent(new CustomEvent("destroyed", { detail: this }));
+        }
+        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
+    }
+    set enabled(val: boolean) {
+        if (this.__destroyed) {
+            if (isDevEnvironment()) {
+                console.warn(`[Needle Engine Dev] Trying to ${val ? "enable" : "disable"} destroyed component`);
+            }
+            return;
+        }
+        // when called from animationclip we receive numbers
+        // due to interpolation they can be anything between 0 and 1
+        if (typeof val === "number") {
+            if (val >= 0.5) val = true;
+            else val = false;
+        }
+
+        // need to check here because codegen is calling this before everything is setup
+        if (!this.__didAwake) {
+            this.__isEnabled = val;
+            return;
+        }
+        if (val) {
+            this.__internalEnable();
+        } else {
+            this.__internalDisable();
+        }
+    }
+
+    /**
+     * Gets the position of this component's GameObject in world space.    
+     * Note: This is equivalent to calling `this.gameObject.worldPosition`
+     */
+    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
+     * Note: This is equivalent to calling `this.gameObject.worldQuaternion`
+     */
+    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);
+    }
+
+    /**
+     * Gets the rotation of this component's GameObject in world space as Euler angles (in radians)
+     */
+    get worldEuler(): Euler {
+        return threeutils.getWorldEuler(this.gameObject);
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)  
+     * Note: This is equivalent to calling `this.gameObject.worldRotation`
+     */
+    get worldRotation(): Vector3 {
+        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();
+    /**
+     * 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();
+    /**
+     * 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();
+    /**
+     * 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];
+        for (let i = 0; i < listeners.length; i++) {
+            listeners[i](evt);
+        }
+
+        return false;
+    }
+}
+
+// For legacy reasons we need to export this as well 
+// (and we don't use extend to inherit the component docs)
+export { Component as Behaviour };