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 { isHotReloadEnabled, registerHotReloadType, unregisterHotReloadType } from "../engine/engine_hot_reload.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 { $componentName, type Collision, type ComponentInit, type Constructor, type ConstructorConcrete, type GuidsMap, type ICollider, type IComponent, type IGameObject, type SourceIdentifier } from "../engine/engine_types.js";
import { TypeStore } from "../engine/engine_typestore.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 @typescript-eslint/no-deprecated
    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;
    abstract set worldForward(val: 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` */
    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
     * @param includeInactive Whether to include inactive objects in the search
     * @returns The first matching component if found, otherwise null
     */
    public static getComponentInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>, includeInactive: boolean = false): T | null {
        return getComponentInChildren(go, typeName, includeInactive);
    }

    /**
     * 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'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}. 
 * 
 * **Component lifecycle event methods:**   
 * {@link awake}, {@link start}, {@link onEnable}, {@link onDisable}, {@link onDestroy}, {@link earlyUpdate}, {@link update}, {@link lateUpdate}, {@link onBeforeRender}, {@link onAfterRender}.   
 * 
 * **XR event methods:**   
 * {@link onEnterXR}, {@link onLeaveXR}, {@link onUpdateXR}, {@link onXRControllerAdded} and {@link onXRControllerRemoved}.    
 * 
 * **Input event methods:**   
 * {@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", this.gameObject.name);
 *  }
 *  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; }

    /**
     * Get the original component type name before minification (available if the component is registered in the TypeStore)
     */
    get [$componentName]() { return TypeStore.getKey(this.constructor as any) || undefined; }


    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>);
        if (isHotReloadEnabled()) registerHotReloadType(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);
        if (isHotReloadEnabled()) unregisterHotReloadType(this);
    }

    /**
     * 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 };