import 'three/examples/jsm/renderers/webgl-legacy/nodes/WebGLNodes.js';

import type { SceneData } from 'needle-bindings';
import type { EffectComposer } from "postprocessing";
import {
	BufferGeometry, Camera, Color, DepthTexture, Group,
	Material, NearestFilter, NoToneMapping, Object3D, OrthographicCamera, PCFShadowMap,
	PerspectiveCamera, RGBAFormat, Scene, SRGBColorSpace,
	Texture, WebGLRenderer, type WebGLRendererParameters, WebGLRenderTarget, type WebXRArrayCamera
} from 'three';
/** @ts-ignore (not yet in types?) */
import BasicNodeLibrary from "three/src/renderers/webgpu/nodes/BasicNodeLibrary.js";
import * as Stats from 'three/examples/jsm/libs/stats.module.js';
import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
import { nodeFrame } from "three/examples/jsm/renderers/webgl-legacy/nodes/WebGLNodeBuilder.js";

import { initSpectorIfAvailable } from './debug/debug_spector.js';
import { isDevEnvironment, LogType, showBalloonError, showBalloonMessage } from './debug/index.js';
import { AccessibilityManager } from './engine_accessibility.js';
import { Addressables } from './engine_addressables.js';
import { AnimationsRegistry } from './engine_animation.js';
import { Application } from './engine_application.js';
import { AssetDatabase } from './engine_assetdatabase.js';
import { FocusRect, FocusRectSettings, updateCameraFocusRect } from './engine_camera.js';
import { VERSION } from './engine_constants.js';
import { EventBus } from './engine_context_eventbus.js';
import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
import { WaitForPromise } from './engine_coroutine.js';
import { ObjectUtils } from "./engine_create_objects.js";
import { destroy, foreachComponent } from './engine_gameobject.js';
import { getLoader } from './engine_gltf.js';
import { Input } from './engine_input.js';
import { Telemetry } from './engine_license.js';
import { applyContextReset, resettable } from './engine_context_reset.js';
import { invokeLifecycleFunctions } from './engine_lifecycle_functions_internal.js';
import { type ILightDataRegistry, LightDataRegistry } from './engine_lightdata.js';
import { LODsManager } from "./engine_lods.js";
import * as looputils from './engine_mainloop_utils.js';
import { NetworkConnection } from './engine_networking.js';
import { Physics } from './engine_physics.js';
import { PlayerViewManager } from './engine_playerview.js';
import { getSceneData } from './engine_scenedata.js';
import { RendererData as SceneLighting } from './engine_scenelighting.js';
import { getTempColor, logHierarchy } from './engine_three_utils.js';
import { registerWebGPUPMREMGenerator } from './engine_three_compat.js';
import { Time } from './engine_time.js';
import { patchTonemapping } from './engine_tonemapping.js';
import type { ContextLifecycleMode, CoroutineData, ICamera, IComponent, IContext, ILight, LoadedModel, Model, SourceIdentifier, Vec2 } from "./engine_types.js";
import { deepClone, delay, DeviceUtilities, getParam } from './engine_utils.js';
import type { INeedleXRSessionEventReceiver, NeedleXRSession } from './engine_xr.js';
import { PostProcessing } from './postprocessing/index.js';
import { NeedleMenu } from './webcomponents/needle menu/needle-menu.js';
import type { NeedleEngineWebComponent } from './webcomponents/needle-engine.js';

const debug = getParam("debugcontext");
const stats = getParam("stats");
const debugActive = getParam("debugactive");
const debugframerate = getParam("debugframerate");
const debugCoroutine = getParam("debugcoroutine");

// this is where functions that setup unity scenes will be pushed into
// those will be accessed from our custom html element to load them into their context
export const build_scene_functions: { [name: string]: (context: Context) => Promise<void> } = {};


export declare class LoadingProgressArgs {
	/** the name or URL of the loaded file */
	name: string;
	/** the loading progress event from the loader */
	progress: ProgressEvent;
	/** the index of the loaded file */
	index: number;
	/** the total number of files to load */
	count: number;
}
export declare class ContextCreateArgs {
	/** list of glTF or GLB files to load */
	files: Array<string>;
	abortSignal?: AbortSignal;
	/** called when loading a provided glTF file started */
	onLoadingStart?: (index: number, file: string) => void;
	/** called on update for each loaded glTF file */
	onLoadingProgress?: (args: LoadingProgressArgs) => void;
	/** Called after a gLTF file has finished loading */
	onLoadingFinished?: (index: number, file: string, glTF: Model | null) => void;
}

export class ContextArgs {
	name?: string;
	/** for debugging only */
	alias?: string;
	/** the hash is used as a seed when initially loading the scene files */
	hash?: string;

	/** when true the context will not check if it's visible in the viewport and always update and render */
	runInBackground?: boolean;
	/** the DOM element the context belongs to or is inside of (this does not have to be the canvas. use renderer.domElement if you want to access the dom canvas) */
	domElement?: HTMLElement | null;
	/** externally owned renderer */
	renderer?: WebGLRenderer;
	/** externally owned camera */
	camera?: Camera;
	/** externally owned scene */
	scene?: Scene;
}

/**
 * Represents the different phases of the update cycle in Needle Engine.  
 * Components can register for specific frame events to perform actions at precise moments.  
 * The order of execution is: Start → EarlyUpdate → Update → LateUpdate → OnBeforeRender → OnAfterRender  
 *
 * @see {@link Component.startCoroutine} for using FrameEvent with coroutines
 */
export enum FrameEvent {
	/** Called once when a component starts for the first time */
	Start = -1,
	/** Called at the beginning of each frame, before the main update */
	EarlyUpdate = 0,
	/** The main update phase, called once per frame */
	Update = 1,
	/** Called after all Update callbacks have finished */
	LateUpdate = 2,
	/** Called immediately before the scene is rendered */
	OnBeforeRender = 3,
	/** Called after the scene has been rendered */
	OnAfterRender = 4,
	/** Called before each physics simulation step */
	PrePhysicsStep = 9,
	/** Called after each physics simulation step */
	PostPhysicsStep = 10,
	/** Default value when no specific frame event is set */
	Undefined = -1,
}

/** threejs callback event signature */
export declare type OnRenderCallback = (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void


export function registerComponent(script: IComponent, context?: Context) {
	if (!script) return;
	if (!script.isComponent) {
		if (isDevEnvironment() || debug)
			console.error("Registered script is not a Needle Engine component. \nThe script will be ignored. Please make sure your component extends \"Behaviour\" imported from \"@needle-tools/engine\"\n", script);
		return;
	}
	if (!context) {
		context = Context.Current;
		if (debug) console.warn("> Registering component without context");
	}
	const new_scripts = context?.new_scripts;
	if (!new_scripts.includes(script)) {
		new_scripts.push(script);
	}
}

/**
 * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application.
 * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
 * 
 * The context is automatically created when using the `<needle-engine>` web component.  
 * 
 * @example Accessing the context from a [component](https://engine.needle.tools/docs/api/Behaviour):
 * ```typescript
 * import { Behaviour } from "@needle-tools/engine";
 * import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
 * export class MyScript extends Behaviour {
 *   start() {
 *     console.log("Hello from MyScript");
 *     this.context.scene.add(new Mesh(new BoxGeometry(), new MeshBasicMaterial()));
 *   }
 * }
 * ```
 * 
 * @example Accessing the context from a [hook](https://engine.needle.tools/docs/scripting.html#hooks) without a component e.g. from a javascript module or svelte or react component.
 * 
 * ```typescript
 * import { onStart } from "@needle-tools/engine";
 * 
 * onStart((context) => {
 *   console.log("Hello from onStart hook");
 *   context.scene.add(new Mesh(new BoxGeometry(), new MeshBasicMaterial()));
 * });
 * ```
 * 
 */
export class Context implements IContext {

	private static _defaultTargetFramerate: { value?: number, toString?() } = { value: 90, toString() { return this.value; } }
	/** When a new context is created this is the framerate that will be used by default */
	static get DefaultTargetFrameRate(): number | undefined {
		return Context._defaultTargetFramerate.value;
	}
	/** When a new context is created this is the framerate that will be used by default */
	static set DefaultTargetFrameRate(val: number | undefined) {
		Context._defaultTargetFramerate.value = val;
	}

	private static _defaultWebglRendererParameters: WebGLRendererParameters = {
		antialias: true,
		alpha: false,
		// Note: this is due to a bug on OSX devices. See NE-5370
		powerPreference: (DeviceUtilities.isiOS() || DeviceUtilities.isMacOS()) ? "default" : "high-performance",
		stencil: true,
		// logarithmicDepthBuffer: true,
		// reverseDepthBuffer: true, // https://github.com/mrdoob/three.js/issues/29770
	};
	/** The default parameters that will be used when creating a new WebGLRenderer.  
	 * Modify in global context to change the default parameters for all new contexts.
	 * @example
	 * ```typescript
	 * import { Context } from "@needle-tools/engine";
	 * Context.DefaultWebGLRendererParameters.antialias = false;
	 * ```
	 */
	static get DefaultWebGLRendererParameters(): WebGLRendererParameters {
		return Context._defaultWebglRendererParameters;
	}

	/**
	 * INTERNAL / WORK IN PROGRESS — the `WebGPURenderer` path is **not supported yet**. Do not rely on it.
	 *
	 * When true, new contexts create a `WebGPURenderer({ forceWebGL: true })` instead of a
	 * `WebGLRenderer`, running the unified node/TSL pipeline on the WebGL2 backend. This is an
	 * incomplete prototype, kept private while the renderer migration is in progress. Known gaps:
	 * post-processing and WebXR do not work, and various WebGL-specific renderer paths will break.
	 * @experimental
	 * @internal
	 */
	static ExperimentalWebGPU: boolean = false;

	/** The needle engine version */
	get version() {
		return VERSION;
	}

	/** The currently active context. Only set during the update loops */
	static get Current(): Context {
		return ContextRegistry.Current as Context;
	}

	/** @internal this property should not be set by user code */
	static set Current(context: Context) {
		ContextRegistry.Current = context;
	}

	static get All(): Context[] {
		return ContextRegistry.All as Context[];
	}

	/** The name of the context */
	name: string;
	/** An alias for the context */
	alias: string | undefined | null;
	/** When the renderer or camera are managed by an external process (e.g. when running in r3f context). 
	 * When this is false you are responsible to call update(timestamp, xframe.  
	 * It is also currently assumed that rendering is handled performed by an external process
	 * */
	isManagedExternally: boolean = false;
	/** set to true to pause the update loop. You can receive an event for it in your components.
	 * Note that script updates will not be called when paused */
	isPaused: boolean = false;
	/**
	 * Controls whether component lifecycle and simulation advance during {@link update}.
	 *
	 * - `"running"` (default): the full frame runs — component activation (awake/onEnable/start),
	 *   script updates, coroutines, physics and rendering.
	 * - `"held"`: {@link update} still renders the scene through the full pipeline (camera,
	 *   environment, resize handling, render callbacks) but NO component lifecycle advances:
	 *   nothing awakes, enables, starts or updates, coroutines and physics don't step, and
	 *   newly added components stay queued until the lifecycle runs again.
	 *
	 * Explicit teardown is always allowed: destroying or disabling objects/components while held
	 * still calls onDisable/onDestroy so resources clean up properly.
	 *
	 * Switching back to `"running"` activates everything that was queued or re-activated while
	 * held (normal awake → onEnable → start order). Every change emits a typed
	 * `"lifecycle-changed"` event on {@link events}:
	 * ```ts
	 * context.events.on("lifecycle-changed", e => console.log(e.lifecycle, e.previous));
	 * ```
	 *
	 * Use this to render a scene without running it: pause screens, thumbnail or preview
	 * rendering, preloading, or external tools that host a scene without playing it.
	 */
	get lifecycle(): ContextLifecycleMode {
		return this._lifecycle;
	}
	set lifecycle(value: ContextLifecycleMode) {
		if (value === this._lifecycle) return;
		const previous = this._lifecycle;
		this._lifecycle = value;
		if (previous === "held" && value === "running") {
			this.reconcileLifecycleAfterHold();
		}
		this.events.emit("lifecycle-changed", { context: this, lifecycle: value, previous });
	}
	private _lifecycle: ContextLifecycleMode = "running";

	/**
	 * Called when switching from "held" back to "running": while held, hierarchy active
	 * flags keep updating but activation callbacks are gated. Components that were never
	 * activated are still queued (new_scripts / new_script_start) and are handled by the
	 * regular processing next frame — but components that had already started and were
	 * re-activated while held (e.g. setActive(false) → setActive(true)) are in no queue
	 * and must be re-enabled here.
	 */
	private reconcileLifecycleAfterHold() {
		if (!this.scene) return;
		// Refresh hierarchy flags first (raw three.js changes made while held never ran
		// updateIsActive) — with the gates now open this fires the pending enable/disable
		// events for flag changes it detects.
		looputils.updateIsActive(this.scene, true);
		foreachComponent(this.scene, comp => {
			if (comp["__didAwake"] === true && comp["__didEnable"] !== true && !comp.destroyed && comp.activeAndEnabled) {
				comp.__internalEnable();
			}
		}, true);
	}
	/** When enabled the application will run while not visible on the page */
	runInBackground: boolean = false;
	/** 
	 * Set to the target framerate you want your application to run in (you can use ?stats to check the fps)
	 * Set to undefined if you want to run at the maximum framerate
	 */
	targetFrameRate?: number | { value?: number };

	/** Use a higher number for more accurate physics simulation.   
	 * When undefined physics steps will be 1 for mobile devices and 5 for desktop devices  
	 * Set to 0 to disable physics updates
	 * TODO: changing physics steps is currently not supported because then forces that we get from the character controller and rigidbody et al are not correct anymore - this needs to be properly tested before making this configureable
	*/
	private physicsSteps?: number = 1;

	/** used to append to loaded assets */
	hash?: string;

	/** The `<needle-engine>` web component */
	domElement: NeedleEngineWebComponent | HTMLElement;

	appendHTMLElement(element: HTMLElement) {
		if (this.domElement.shadowRoot)
			return this.domElement.shadowRoot.appendChild(element);
		else return this.domElement.appendChild(element);
	}

	get resolutionScaleFactor() { return this._resolutionScaleFactor; }
	/** use to scale the resolution up or down of the renderer. default is 1 */
	set resolutionScaleFactor(val: number) {
		if (val === this._resolutionScaleFactor) return;
		if (typeof val !== "number") return;
		if (val <= 0) {
			console.error("Invalid resolution scale factor", val);
			return;
		}
		this._resolutionScaleFactor = val;
		this.updateSize();
	}
	private _resolutionScaleFactor: number = 1;

	// domElement.clientLeft etc doesnt return absolute position
	private _boundingClientRectFrame: number = -1;
	private _boundingClientRect: DOMRect | null = null;
	private _domX; private _domY;
	/** update bounding rects + domX, domY */
	private calculateBoundingClientRect() {
		// workaround for mozilla webXR viewer
		if (this.xr) {
			this._domX = 0;
			this._domY = 0;
			return;
		}
		// TODO: cache this
		if (this._boundingClientRectFrame === this.time.frame) return;
		this._boundingClientRectFrame = this.time.frame;
		this._boundingClientRect = this.domElement.getBoundingClientRect();
		this._domX = this._boundingClientRect.x;
		this._domY = this._boundingClientRect.y;
	}

	/** The width of the `<needle-engine>` element on the website */
	get domWidth(): number {
		// for mozilla XR
		if (this.isInAR) return window.innerWidth;
		return this.domElement.clientWidth;
	}
	/** The height of the `<needle-engine>` element on the website */
	get domHeight(): number {
		// for mozilla XR
		if (this.isInAR) return window.innerHeight;
		return this.domElement.clientHeight;
	}
	/** the X position of the `<needle-engine>` element on the website */
	get domX(): number {
		this.calculateBoundingClientRect();
		return this._domX;
	}
	/** the Y position of the `<needle-engine>` element on the website */
	get domY(): number {
		this.calculateBoundingClientRect();
		return this._domY;
	}
	/**
	 * Is a XR session currently active and presenting?
	 * @returns true if the xr renderer is currently presenting
	 */
	get isInXR() { return this.renderer?.xr?.isPresenting || false; }
	/** shorthand for `NeedleXRSession.active`  
	 * Automatically set by NeedleXRSession when a XR session is active 
	 * @returns the active XR session or null if no session is active
	 * */
	xr: NeedleXRSession | null = null;
	/**
	 * Shorthand for `this.xr?.mode`. AR or VR
	 * @returns the current XR session mode (immersive-vr or immersive-ar)
	 */
	get xrSessionMode() { return this.xr?.mode; }
	/** Shorthand for `this.xrSessionMode === "immersive-vr"` 
	 * @returns true if a webxr VR session is currently active. 
	 */
	get isInVR() { return this.xrSessionMode === "immersive-vr"; }
	/**
	 * Shorthand for `this.xrSessionMode === "immersive-ar"`
	 * @returns true if a webxr AR session is currently active.
	 */
	get isInAR() { return this.xrSessionMode === "immersive-ar"; }
	/** If a XR session is active and in pass through mode (immersive-ar on e.g. Quest) 
	 * @returns true if the XR session is in pass through mode
	 */
	get isInPassThrough() { return this.xr ? this.xr.isPassThrough : false; }
	/** access the raw `XRSession` object (shorthand for `context.renderer.xr.getSession()`). For more control use `NeedleXRSession.active` */
	get xrSession() { return this.renderer?.xr?.getSession(); }
	/** @returns the latest XRFrame (if a XRSession is currently active)
	 * @link https://developer.mozilla.org/en-US/docs/Web/API/XRFrame
	 */
	get xrFrame() { return this._xrFrame }
	/** @returns the current WebXR camera while the WebXRManager is active (shorthand for `context.renderer.xr.getCamera()`) */
	get xrCamera(): WebXRArrayCamera | undefined { return this.renderer.xr.isPresenting ? this.renderer?.xr?.getCamera() : undefined }
	private _xrFrame: XRFrame | null = null;
	/**
	 * The AR overlay element is used to display 2D HTML elements while a AR session is active.
	 */
	get arOverlayElement(): HTMLElement {
		const el = this.domElement as any;
		if (typeof el.getAROverlayContainer === "function")
			return el.getAROverlayContainer();
		return this.domElement;
	}
	/** 
	 * Current event of the update cycle (e.g. `FrameEvent.EarlyUpdate` or `FrameEvent.OnBeforeRender`)
	 */
	get currentFrameEvent(): FrameEvent {
		return this._currentFrameEvent;
	}
	private _currentFrameEvent: FrameEvent = FrameEvent.Undefined;

	/**
	 * The scene contains all objects in the hierarchy and is automatically rendered by the context every frane.
	 */
	scene: Scene;
	/**
	 * The renderer is used to render the scene. It is automatically created when the context is created.
	 */
	renderer!: WebGLRenderer;
	/**
	 * The effect composer used for rendering postprocessing effects.
	 * @deprecated Use `context.postprocessing.composer` instead.
	 */
	get composer(): EffectComposer | ThreeEffectComposer | null { return this.postprocessing.composer; }
	set composer(value: EffectComposer | ThreeEffectComposer | null) { this.postprocessing.composer = value; }

	// #region internal script lists
	/**
	 * @internal All known components. Don't use directly
	 */
	@resettable() readonly scripts: IComponent[] = [];
	/**
	 * @internal All paused components. Don't use directly
	 */
	@resettable() readonly scripts_pausedChanged: IComponent[] = [];
	/**
	 * @internal All components that have a early update event. Don't use directly
	 */
	@resettable() readonly scripts_earlyUpdate: IComponent[] = [];
	/**
	 * @internal All components that have a update event. Don't use directly
	 */
	@resettable() readonly scripts_update: IComponent[] = [];
	/**
	 * @internal All components that have a late update event. Don't use directly
	 */
	@resettable() readonly scripts_lateUpdate: IComponent[] = [];
	/**
	 * @internal All components that have a onBeforeRender event. Don't use directly
	 */
	@resettable() readonly scripts_onBeforeRender: IComponent[] = [];
	/**
	 * @internal All components that have a onAfterRender event. Don't use directly
	 */
	@resettable() readonly scripts_onAfterRender: IComponent[] = [];
	/**
	 * @internal All components that have coroutines. Don't use directly
	 */
	@resettable() readonly scripts_WithCorroutines: IComponent[] = [];
	/**
	 * @internal Components with immersive-vr event methods. Don't use directly
	 */
	@resettable() readonly scripts_immersive_vr: INeedleXRSessionEventReceiver[] = [];
	/**
	 * @internal Components with immersive-ar event methods. Don't use directly
	 */
	@resettable() readonly scripts_immersive_ar: INeedleXRSessionEventReceiver[] = [];
	/**
	 * @internal Coroutine data
	 */
	@resettable() readonly coroutines: { [FrameEvent: number]: Array<CoroutineData> } = {}

	/** callbacks called once after the context has been created */
	@resettable("keep") readonly post_setup_callbacks: Function[] = [];
	/** called every frame at the beginning of the frame (after component start events and before earlyUpdate)
	 * — not reset: engine subsystems register here at construction (e.g. Addressables, RendererData) */
	@resettable("keep") readonly pre_update_callbacks: Function[] = [];
	/** called every frame before rendering (after all component events)
	 * — not reset: render-infrastructure channel, registrations outlive scene content */
	@resettable("keep") readonly pre_render_callbacks: Array<(frame: XRFrame | null) => void> = [];
	/** called every frame after rendering (after all component events)
	 * — not reset: engine subsystems register here at construction (e.g. input end-of-frame) */
	@resettable("keep") readonly post_render_callbacks: Function[] = [];
	/** called every frame befroe update (this list is emptied every frame) */
	@resettable() readonly pre_update_oneshot_callbacks: Function[] = [];

	/** @internal */
	@resettable() readonly new_scripts: IComponent[] = [];
	/** @internal */
	@resettable() readonly new_script_start: IComponent[] = [];
	/** @internal */
	@resettable() readonly new_scripts_pre_setup_callbacks: Function[] = [];
	/** @internal */
	@resettable() readonly new_scripts_post_setup_callbacks: Function[] = [];
	/** @internal */
	@resettable() readonly new_scripts_xr: INeedleXRSessionEventReceiver[] = [];

	// #endregion
	// #region Properties

	/** 
	 * The **main camera component** of the scene - this camera is used for rendering.  
	 * Use `setCurrentCamera` for updating the main camera.
	 */
	@resettable("undefined") mainCameraComponent: ICamera | undefined = undefined;

	/** 
	 * The main camera of the scene - this camera is used for rendering   
	 * Use `setCurrentCamera` for updating the main camera.
	 */
	/**
	 * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
	 * Types are generated automatically from your GLB files when the dev server starts.
	 *
	 * You can store references to objects or components for later use.
	 * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
	 * in which case stored references may become stale.
	 *
	 * @experimental This API may change in future versions.
	 *
	 * @example
	 * // Toggle auto-rotate on the orbit camera
	 * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
	 *
	 * @example
	 * // Change the background color
	 * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
	 */
	get sceneData(): SceneData {
		return getSceneData(this);
	}

	get mainCamera(): Camera {
		if (this._mainCamera) {
			return this._mainCamera;
		}
		if (this.mainCameraComponent) {
			const cam = this.mainCameraComponent as ICamera;
			if (!cam.threeCamera)
				cam.buildCamera();
			return cam.threeCamera;
		}
		if (!this._fallbackCamera) {
			this._fallbackCamera = new PerspectiveCamera(/** default FOV, keep in sync with CameraUtils */ 35, this.domWidth / this.domHeight, 0.1, 1000);
			// Put the fallback into the scene graph. Without this, callers who
			// do `ctx.mainCamera.add(child)` end up parenting children to an
			// orphan camera that the renderer never traverses (since
			// `renderer.render(scene, camera)` walks `scene`, not `camera`).
			// Safe because this branch only runs before a real main camera
			// component exists, and the fallback is replaced once one does.
			this.scene?.add(this._fallbackCamera);
		}
		return this._fallbackCamera;
	}
	/** Set the main camera of the scene. If set to null the camera of the {@link mainCameraComponent} will be used - this camera is used for rendering */
	set mainCamera(cam: Camera | null) {
		this._mainCamera = cam;
	}
	@resettable("null") private _mainCamera: Camera | null = null;
	@resettable("null") private _fallbackCamera: PerspectiveCamera | null = null;

	/** access application state (e.g. if all audio should be muted) */
	get application(): Application { return this._application; }
	private _application!: Application;
	/** access animation mixer used by components in the scene */
	get animations(): AnimationsRegistry { return this._animations; }
	private _animations!: AnimationsRegistry;
	/** access timings (current frame number, deltaTime, timeScale, ...) */
	get time(): Time { return this._time; }
	private _time!: Time;
	/** access input data (e.g. click or touch events) */
	get input(): Input { return this._input; }
	private _input!: Input;
	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
	get physics(): Physics { return this._physics; }
	private _physics!: Physics;
	/** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
	get postprocessing(): PostProcessing { return this._postprocessing; }
	private _postprocessing!: PostProcessing;
	/** access networking methods (use it to send or listen to messages or join a networking backend) */
	get connection(): NetworkConnection { return this._connection; }
	private _connection!: NetworkConnection;
	/** context-level event bus for decoupled component communication
	 * @see {@link ContextEventMap} for known event types
	 */
	get events(): EventBus { return this._events; }
	/** replaced via {@link resetSubsystems} (shared with clear) */
	@resettable("custom") private _events = new EventBus();
	/**  @deprecated AssetDatabase is deprecated */
	assets: AssetDatabase;

	/** All registered lights in the scene, maintained by the Light component. 
	 * @see mainLight for accessing the main directional light in the scene
	 */
	/** reset via {@link resetSubsystems} (shared with clear) */
	@resettable("custom") readonly lights = new Array<ILight>();

	/** The brightest registered directional light, or null if none are registered
	 * @see lights
	 */
	get mainLight(): ILight | null {
		let best: ILight | null = null;
		for (const light of this.lights) {
			if (light.type !== "directional") continue;
			if (!best || light.intensity > best.intensity) best = light;
		}
		return best;
	}

	/** @deprecated Use sceneLighting */
	private get rendererData() { return this.sceneLighting }

	/** Access the scene lighting manager to control lighting settings in the context */
	readonly sceneLighting: SceneLighting;
	readonly addressables: Addressables;
	readonly lightmaps: ILightDataRegistry;
	readonly players: PlayerViewManager;

	/** Access the LODs manager to control LOD behavior in the context */
	readonly lodsManager: LODsManager;
	/** Access the needle menu to add or remove buttons to the menu element */
	readonly menu: NeedleMenu;

	readonly accessibility: AccessibilityManager;

	/** 
	 * Checks if the context is fully created and ready
	 * @returns true if the context is fully created and ready 
	 */
	get isCreated() { return this._isCreated; }

	/** 
	 * The source identifier(s) of the root scene(s) loaded into this context.
	 * When using `<needle-engine>` web component this will be the `src` attribute(s).
	 * @returns The source identifier for of the root scene
	*/
	get rootSourceId(): SourceIdentifier | undefined { return this.rootSceneSourceIdentifiers[0] || undefined; }

	private _needsUpdateSize: boolean = false;
	private _isCreated: boolean = false;
	private _isCreating: boolean = false;
	private _isVisible: boolean = false;

	private _stats = stats ? new Stats.default() : null;

	constructor(args?: ContextArgs) {
		this.name = args?.name || "";
		this.alias = args?.alias;
		this.domElement = args?.domElement || document.body;
		this.hash = args?.hash;

		if (args?.renderer) {
			this.renderer = args.renderer;
			this.isManagedExternally = true;
		}
		if (args?.runInBackground !== undefined) this.runInBackground = args.runInBackground;
		if (args?.scene) this.scene = args.scene;
		else this.scene = new Scene();
		if (this._fallbackCamera && !this._fallbackCamera.parent) {
			this.scene.add(this._fallbackCamera);
		}
		if (args?.camera) this._mainCamera = args.camera;

		this._application = new Application(this);
		this._time = new Time();
		this._input = new Input(this);
		this._physics = new Physics(this);
		this._postprocessing = new PostProcessing(this);
		this._connection = new NetworkConnection(this);
		// eslint-disable-next-line @typescript-eslint/no-deprecated
		this.assets = new AssetDatabase();
		this.sceneLighting = new SceneLighting(this);
		this.addressables = new Addressables(this);
		this.lightmaps = new LightDataRegistry(this);
		this.players = new PlayerViewManager(this);
		this.menu = new NeedleMenu(this);
		this.lodsManager = new LODsManager(this);
		this._animations = new AnimationsRegistry(this);
		this.accessibility = new AccessibilityManager(this);


		const resizeCallback = () => this._needsUpdateSize = true;
		window.addEventListener('resize', resizeCallback);
		this._disposeCallbacks.push(() => window.removeEventListener('resize', resizeCallback));

		const resizeObserver = new ResizeObserver(_ => this._needsUpdateSize = true);
		resizeObserver.observe(this.domElement);
		this._disposeCallbacks.push(() => resizeObserver.disconnect());

		this._intersectionObserver = new IntersectionObserver(entries => {
			this._isVisible = entries[0].isIntersecting;
		});
		this._disposeCallbacks.push(() => this._intersectionObserver?.disconnect());

		ContextRegistry.register(this);
	}

	// #region Renderer
	/** 
	 * Calling this function will dispose the current renderer and create a new one which will then be assigned to the context. It can be used to create a new renderer with custom WebGLRendererParameters.   
	 * **Note**: Instead you can also modify the static `Context.DefaultWebGlRendererParameters` before the context is created.  
	 * **Note**: This method is recommended because it re-uses an potentially already existing canvas element. This is necessary to keep input event handlers from working (e.g. components like OrbitControls subscribe to input events on the canvas)
	 * @returns {WebGLRenderer} the newly created renderer
	 */
	async createNewRenderer(params?: WebGLRendererParameters) {
		this.renderer?.dispose();

		params = { ...Context.DefaultWebGLRendererParameters, ...params };
		if (!params.canvas) {
			// get canvas already configured in the Needle Engine Web Component
			const canvas = this.domElement?.shadowRoot?.querySelector("canvas");
			if (canvas) {
				params.canvas = canvas;
				if (debug) {
					console.log("Using canvas from shadow root", canvas);
				}
			}
			else if(debug) console.warn("No canvas found in shadow root, creating new canvas. This may cause input events to not work correctly. To fix this, make sure to use the canvas provided by the Needle Engine Web Component (e.g. by using context.createNewRenderer() without parameters or passing the canvas from the shadow root explicitly).")
		}
		if (debug) console.log("Using Renderer Parameters:", params, this.domElement)

		if (Context.ExperimentalWebGPU) {
			// EXPERIMENTAL: WebGPURenderer with a WebGL2 backend (forceWebGL). Dynamic import so the
			// three/webgpu module only loads when opted in (the needle alias maps it to three/src so
			// it shares the same three instance). Cast to WebGLRenderer for the shared API — note that
			// post-processing and WebXR are NOT supported in this mode yet.
			const { WebGPURenderer, PMREMGenerator: WebGPUPMREMGenerator } = await import("three/webgpu");
			const webgpu = new WebGPURenderer({ forceWebGL: true, canvas: params.canvas as HTMLCanvasElement | undefined, antialias: params.antialias, alpha: params.alpha });
			await webgpu.init();
			this.renderer = webgpu as unknown as WebGLRenderer;
			// Register the backend-agnostic PMREMGenerator (three/webgpu) with the compat module so
			// createPMREMGenerator() can use it. Grabbed here since three/webgpu is already loaded.
			registerWebGPUPMREMGenerator(WebGPUPMREMGenerator);
			console.warn(`[Needle] EXPERIMENTAL WebGPURenderer active (${(this.renderer as any).backend?.isWebGPUBackend ? "WebGPU" : "WebGL2"} backend). Post-processing & WebXR are not supported in this mode.`);
		}
		else {
			this.renderer = new WebGLRenderer(params);
		}

		this.renderer.domElement.setAttribute("aria-label", "3D rendering");
		this.renderer.domElement.setAttribute("role", "img");

		if (!Context.ExperimentalWebGPU) this.renderer.debug.checkShaderErrors = isDevEnvironment() || getParam("checkshadererrors") === true;

		// some tonemapping other than "NONE" is required for adjusting exposure with EXR environments
		this.renderer.toneMappingExposure = 1; // range [0...inf] instead of the usual -15..15
		this.renderer.toneMapping = NoToneMapping; // could also set to LinearToneMapping, ACESFilmicToneMapping

		this.renderer.setClearColor(new Color('lightgrey'), 0);
		// // @ts-ignore
		// this.renderer.alpha = false;
		this.renderer.shadowMap.enabled = true;
		this.renderer.shadowMap.type = PCFShadowMap;
		this.renderer.setSize(this.domWidth, this.domHeight);
		this.renderer.outputColorSpace = SRGBColorSpace;

		if (!Context.ExperimentalWebGPU) {
			// Injecting the core nodes library here, like WebGPURenderer backends do
			// In r183, three.js reads renderer.library directly (not renderer.nodes.library)
			//@ts-ignore
			this.renderer.library = new BasicNodeLibrary();
		}
		// this.renderer.toneMapping = AgXToneMapping;
		this.lodsManager.setRenderer(this.renderer);

		this.input.bindEvents();

		initSpectorIfAvailable(this, this.renderer.domElement);

		return this.renderer;
	}


	private _intersectionObserver: IntersectionObserver | null = null;
	private internalOnUpdateVisible() {
		this._intersectionObserver?.disconnect();
		this._intersectionObserver?.observe(this.domElement);
	}

	/** context-lifetime teardown callbacks (resize listener, observers) — only run on dispose, must survive reset */
	@resettable("keep") private _disposeCallbacks: Function[] = [];


	/** will request a renderer size update the next render call (will call updateSize the next update) */
	requestSizeUpdate() { this._needsUpdateSize = true; }

	/** Clamps the renderer max resolution. If undefined the max resolution is not clamped. Default is undefined */
	maxRenderResolution?: Vec2;

	/** Control the renderer devicePixelRatio.  
	 * **Options**   
	 * - `auto` - Needle Engine automatically sets the pixel ratio to the current window.devicePixelRatio.
	 * - `manual` - Needle Engine will not change the renderer pixel ratio. You can set it manually.
	 * - `number` - Needle Engine will set the pixel ratio to the given number. The change will be applied to the renderer and the composer (if used) at the end of the current frame.
	 */
	get devicePixelRatio() { return this._devicePixelRatio; }
	set devicePixelRatio(val: "auto" | "manual" | number) {
		if (val !== this._devicePixelRatio) {
			this._devicePixelRatio = val;
			this._needsUpdateSize = true;
		}
	}
	private _devicePixelRatio: "auto" | "manual" | number = "auto";

	/** 
	 * Update the renderer and canvas size. This is also automatically called when a DOM size change is detected.
	 */
	updateSize(force: boolean = false) {
		if (force || (!this.isManagedExternally && this.renderer.xr?.isPresenting === false)) {
			this._needsUpdateSize = false;
			const scaleFactor = this.resolutionScaleFactor;
			let width = this.domWidth * scaleFactor;
			let height = this.domHeight * scaleFactor;
			if (this.maxRenderResolution) {
				this.maxRenderResolution.x = Math.max(1, this.maxRenderResolution.x);
				width = Math.min(this.maxRenderResolution.x, width);
				this.maxRenderResolution.y = Math.max(1, this.maxRenderResolution.y);
				height = Math.min(this.maxRenderResolution.y, height);
			}
			const camera = this.mainCamera as PerspectiveCamera;
			this.updateAspect(camera);
			this.renderer.setSize(width, height, true);
			// avoid setting pixel values here since this can cause pingpong updates
			// e.g. when system scale is set to 125%
			// https://github.com/needle-tools/needle-engine-support/issues/69
			this.renderer.domElement.style.width = "100%";
			this.renderer.domElement.style.height = "100%";

			const devicePixelRatio = typeof this.devicePixelRatio === "number"
				? this.devicePixelRatio
				: this.devicePixelRatio === "auto"
					? Math.min(2, window.devicePixelRatio) // clamp device pixel ratio to two for "automatic" mode
					: undefined;
			if (devicePixelRatio !== undefined) {
				this.renderer.setPixelRatio(devicePixelRatio);
			}

			if (this.composer) {
				this.composer.setSize?.call(this.composer, width, height);
				if (devicePixelRatio !== undefined && "setPixelRatio" in this.composer && typeof this.composer.setPixelRatio === "function")
					this.composer.setPixelRatio?.call(this.composer, window.devicePixelRatio);
			}
		}
	}

	/**
	 * Update the camera aspect ratio or orthorgraphic camera size. This is automatically called when a DOM size change is detected.
	 */
	updateAspect(camera: PerspectiveCamera | OrthographicCamera, width?: number, height?: number) {
		if (!camera) return;
		if (width === undefined)
			width = this.domWidth;
		if (height === undefined)
			height = this.domHeight;
		const aspectRatio = width / height;
		if ((camera as PerspectiveCamera).isPerspectiveCamera) {
			const cam = camera as PerspectiveCamera;
			const pa = cam.aspect;
			cam.aspect = aspectRatio;
			if (pa !== cam.aspect)
				camera.updateProjectionMatrix();
		}
		else if ((camera as OrthographicCamera).isOrthographicCamera) {
			const cam = camera as OrthographicCamera;
			// Maintain the camera's current vertical size (top - bottom)
			const verticalSize = cam.top - cam.bottom;
			// Calculate new horizontal size based on aspect ratio
			const horizontalSize = verticalSize * aspectRatio;
			// Update camera bounds while maintaining center position
			const halfWidth = horizontalSize / 2;
			const halfHeight = verticalSize / 2;
			if (cam.left != -halfWidth || cam.top != halfHeight) {
				cam.left = -halfWidth;
				cam.right = halfWidth;
				cam.top = halfHeight;
				cam.bottom = -halfHeight;
				camera.updateProjectionMatrix();
			}
		}
	}

	/** This will recreate the whole needle engine context and dispose the whole scene content  
	 * All content will be reloaded (loading times might be faster due to browser caches)   
	 * All scripts will be recreated */
	recreate() {
		this.clear();
		this.create(this._originalCreationArgs);
	}

	private _originalCreationArgs?: ContextCreateArgs;

	/** @deprecated use create. This method will be removed in a future version */
	async onCreate(opts?: ContextCreateArgs) {
		return this.create(opts);
	}
	/** @internal */
	async create(opts?: ContextCreateArgs) {
		try {
			this._isCreating = true;
			if (opts !== this._originalCreationArgs)
				this._originalCreationArgs = deepClone(opts);
			window.addEventListener("unhandledrejection", this.onUnhandledRejection)
			const res = await this.internalOnCreate(opts);
			this._isCreated = res;
			return res;
		}
		finally {
			window.removeEventListener("unhandledrejection", this.onUnhandledRejection)
			this._isCreating = false;
		}
	}

	private onUnhandledRejection = (event: PromiseRejectionEvent) => {
		this.onError(event.reason);
	};

	/** Dispatches an error */
	private onError(error: string) {
		this.domElement.dispatchEvent(new CustomEvent("error", { detail: error }));
	}

	/** 
	 * Clears the context and destroys all scenes and objects in the scene.   
	 * The ContextCleared event is called at the end.   
	 * This is automatically called when e.g. the `src` attribute changes on `<needle-engine>`   
	 * or when the web component is removed from the DOM
	 */
	clear() {
		ContextRegistry.dispatchCallback(ContextEvent.ContextClearing, this);
		invokeLifecycleFunctions(this, ContextEvent.ContextClearing);
		// NOTE: this does dispose the environment/background image too
		// which is probably not desired if it is set via the background-image attribute
		destroy(this.scene, true, true);
		this.scene = new Scene();
		// Drop cached camera references — `destroy(scene, true, true)` above
		// runs `disposeObjectResources` over the old tree, which sets
		// `visible = false` on every Object3D it touches. Anything we still
		// hold a reference to (the fallback camera, an explicit `_mainCamera`
		// override) is now a disposed corpse: detached from the new scene,
		// invisible, useless. Re-create on next access against the fresh scene.
		this._fallbackCamera = null;
		this._mainCamera = null;
		this.addressables?.dispose();
		this.lightmaps?.clear();
		this.accessibility?.clear();

		this.resetSubsystems();

		if (!this.isManagedExternally) {
			if (this.renderer) {
				this.renderer.renderLists.dispose();
				this.renderer.state.reset();
				this.renderer.resetState();
			}
		}
		// We do not want to clear the renderer here because when switching src we want to keep the last rendered frame in case the loading screen is not visible
		// if a user wants to see the background they can still call setClearAlpha(0) and clear manually
		ContextRegistry.dispatchCallback(ContextEvent.ContextCleared, this);
	}

	/**
	 * Resets the **runtime execution state** of the context — NOT your application:
	 * the scene and all objects, components and GPU resources are left untouched.
	 * What is reset: all script registrations and activation queues are dropped, coroutines
	 * are stopped, the physics world is disposed (a fresh one is created on next use), the
	 * event bus is replaced and camera assignments are cleared.
	 *
	 * This is an advanced API for hosts that unload a running world but keep the context
	 * alive. Typical use cases:
	 * - **play/stop cycles in external tools** (e.g. an editor): `destroy()` the played scene,
	 *   `resetRuntimeState()`, then assign the scene to show next — often combined with
	 *   {@link lifecycle} = `"held"`.
	 * - **scene switching** that replaces `context.scene` wholesale without recreating the
	 *   context (and without {@link clear}'s GPU disposal).
	 * - **test harnesses** that need a pristine execution state between test cases.
	 *
	 * Unlike {@link clear} nothing is destroyed or disposed and NO lifecycle callbacks run —
	 * `destroy()` scene content you want torn down properly BEFORE calling this. Components
	 * that are still alive when this is called are simply unregistered: they stop updating,
	 * their onDisable/onDestroy never runs (side effects like event listeners or timers leak),
	 * and any physics state they referenced dies with the physics world — a dev-mode warning
	 * reports such components. Unregistered components can be registered again via
	 * `GameObject.add`.
	 *
	 * NOT reset, deliberately: content registries (addressables, lightmaps, accessibility —
	 * they belong to loaded content, which this method does not manage) and the persistent
	 * per-frame callback lists (`pre_update_callbacks`/`pre_render_callbacks`/
	 * `post_render_callbacks` — engine subsystems register there at construction).
	 */
	resetRuntimeState() {
		if (this.isInXR) {
			throw new Error("Context.resetRuntimeState() is not supported during an active XR session. End the session first.");
		}
		// live components dropped here are never torn down — surface the misuse.
		// some() exits on the first live script; the list is only built when warning.
		if (isDevEnvironment() && this.scripts.some(script => !script.destroyed)) {
			const live = this.scripts.filter(script => !script.destroyed);
			console.warn(
				`Context.resetRuntimeState() dropped ${live.length} live component(s) without teardown — ` +
				`their onDisable/onDestroy will never run and resources they hold (event listeners, timers, physics state) leak. ` +
				`Call destroy() on scene content before resetting.`,
				live.slice(0, 10));
		}
		// All fields classified via @resettable: script registrations, activation queues,
		// coroutines, one-shot callbacks, camera assignments. A test enforces that every
		// mutable collection field on the context carries a classification.
		applyContextReset(this);
		// Module-level context-keyed state — outside the instance, not coverable by field decorators:
		looputils.clearPrewarmList(this);
		// Behavioral resets shared with clear(): physics world, render listeners, event bus, lights
		this.resetSubsystems();
	}

	/** Shared between {@link clear} and {@link resetRuntimeState}: disposes the physics world,
	 * clears the render listeners, replaces the event bus and empties the lights list. */
	private resetSubsystems() {
		this.physics?.engine?.dispose();

		this._onBeforeRenderListeners.clear();
		this._onAfterRenderListeners.clear();
		this._events.clear();
		this._events = new EventBus();

		this.lights.length = 0;
	}

	/**
	 * Dispose all allocated resources and clears the scene. This is automatically called e.g. when the `<needle-engine>` component is removed from the DOM.
	 */
	dispose() {
		this.internalOnDestroy();
		this.accessibility.dispose();
	}

	/**@deprecated use dispose()  */
	onDestroy() { this.internalOnDestroy(); }

	private internalOnDestroy() {
		Context.Current = this;
		ContextRegistry.dispatchCallback(ContextEvent.ContextDestroying, this);
		invokeLifecycleFunctions(this, ContextEvent.ContextDestroying);
		this.clear();
		// Unhook the LOD render patch and remove this context's lodsManager from the
		// global gltf-progressive plugin registry before the renderer goes away.
		// Other clear() callsites keep the renderer alive and don't need this.
		this.lodsManager.disable();
		this.renderer?.setAnimationLoop(null);
		if (this.renderer) {
			this.renderer.setClearAlpha(0);
			this.renderer.clear();
			if (!this.isManagedExternally) {
				if (debug) console.log("Disposing renderer");
				this.renderer.dispose();
			}
		}
		this.scene = null!;
		this.renderer = null!;
		this.input.dispose();
		this.connection.dispose();
		this.menu.onDestroy();
		this.animations.onDestroy();
		for (const cb of this._disposeCallbacks) {
			try {
				cb();
			}
			catch (e) {
				console.error("Error in on dispose callback:", e, cb);
			}
		}
		if (this.domElement?.parentElement) {
			this.domElement.parentElement.removeChild(this.domElement);
		}
		this._isCreated = false;
		ContextRegistry.dispatchCallback(ContextEvent.ContextDestroyed, this);
		invokeLifecycleFunctions(this, ContextEvent.ContextDestroyed);
		ContextRegistry.unregister(this);
		if (Context.Current === this) {
			//@ts-ignore
			Context.Current = null;
		}
	}

	/** @internal Automatically called by components when you call `startCoroutine`. Use `startCoroutine` instead  */
	registerCoroutineUpdate(script: IComponent, coroutine: Generator, evt: FrameEvent): Generator {
		if (typeof coroutine?.next !== "function") {
			console.error("Registered invalid coroutine function from " + script.name + "\nCoroutine functions must be generators: \"*myCoroutine() {...}\"\nStart a coroutine from a component by calling \"this.startCoroutine(myCoroutine())\"")
			return coroutine;
		}
		if (!this.coroutines[evt]) this.coroutines[evt] = [];
		this.coroutines[evt].push({ comp: script, main: coroutine });
		return coroutine;
	}

	/** @internal Automatically called by components. */
	unregisterCoroutineUpdate(coroutine: Generator, evt: FrameEvent): void {
		if (!this.coroutines[evt]) return;
		const idx = this.coroutines[evt].findIndex(c => c.main === coroutine);
		if (idx >= 0) this.coroutines[evt].splice(idx, 1);
	}

	/** @internal Automatically called */
	stopAllCoroutinesFrom(script: IComponent) {
		for (const evt in this.coroutines) {
			const rout: CoroutineData[] = this.coroutines[evt];
			for (let i = rout.length - 1; i >= 0; i--) {
				const r = rout[i];
				if (r.comp === script) {
					rout.splice(i, 1);
				}
			}
		}
	}

	@resettable() private _cameraStack: ICamera[] = [];

	/** Change the main camera */
	setCurrentCamera(cam: ICamera) {
		if (!cam) return;
		if (!cam.threeCamera) cam.buildCamera(); // < to build camera
		if (!cam.threeCamera) {
			console.warn("Camera component is missing camera", cam)
			return;
		}
		const index = this._cameraStack.indexOf(cam);
		if (index >= 0) this._cameraStack.splice(index, 1);
		this._cameraStack.push(cam);
		this.mainCameraComponent = cam;
		const camera = cam.threeCamera as PerspectiveCamera;
		if (camera.isPerspectiveCamera)
			this.updateAspect(camera);
		(this.mainCameraComponent as ICamera)?.applyClearFlagsIfIsActiveCamera();
	}

	/**
	 * Remove the camera from the mainCamera stack (if it has been set before with `setCurrentCamera`)
	 */
	removeCamera(cam?: ICamera | null) {
		if (!cam) return;
		const index = this._cameraStack.indexOf(cam);
		if (index >= 0) this._cameraStack.splice(index, 1);

		if (this.mainCameraComponent === cam) {
			this.mainCameraComponent = undefined;

			if (this._cameraStack.length > 0) {
				const last = this._cameraStack[this._cameraStack.length - 1];
				this.setCurrentCamera(last);
			}
		}
	}

	// #region onBeforeRender / onAfterRender listeners
	/** reset via {@link resetSubsystems} (shared with clear) */
	@resettable("custom") private readonly _onBeforeRenderListeners = new Map<string, OnRenderCallback[]>();
	/** reset via {@link resetSubsystems} (shared with clear) */
	@resettable("custom") private readonly _onAfterRenderListeners = new Map<string, OnRenderCallback[]>();

	/** Use to subscribe to onBeforeRender events on threejs objects.
	 * @link https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender
	 */
	addBeforeRenderListener(target: Object3D, callback: OnRenderCallback) {
		if (!this._onBeforeRenderListeners.has(target.uuid)) {
			const arr: OnRenderCallback[] = [];
			this._onBeforeRenderListeners.set(target.uuid, arr);
			target.onBeforeRender = this._createRenderCallbackWrapper(arr);
		}
		this._onBeforeRenderListeners.get(target.uuid)!.push(callback);
	}
	/** Remove callback from three `onBeforeRender` event (if it has been added with `addBeforeRenderListener(...)`)
	 * @link https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender
	*/
	removeBeforeRenderListener(target: Object3D, callback: OnRenderCallback) {
		if (this._onBeforeRenderListeners.has(target.uuid)) {
			const arr = this._onBeforeRenderListeners.get(target.uuid)!;
			const idx = arr.indexOf(callback);
			if (idx >= 0) arr.splice(idx, 1);
		}
	}

	/** 
	 * Subscribe to onAfterRender events on threejs objects 
	 * @link https://threejs.org/docs/#api/en/core/Object3D.onAfterRender
	*/
	addAfterRenderListener(target: Object3D, callback: OnRenderCallback) {
		if (!this._onAfterRenderListeners.has(target.uuid)) {
			const arr = [];
			this._onAfterRenderListeners.set(target.uuid, arr);
			target.onAfterRender = this._createRenderCallbackWrapper(arr);
		}
		this._onAfterRenderListeners.get(target.uuid)?.push(callback);
	}
	/** 
	 * Remove from onAfterRender events on threejs objects 
	 * @link https://threejs.org/docs/#api/en/core/Object3D.onAfterRender
	*/
	removeAfterRenderListener(target: Object3D, callback: OnRenderCallback) {
		if (this._onAfterRenderListeners.has(target.uuid)) {
			const arr = this._onAfterRenderListeners.get(target.uuid)!;
			const idx = arr.indexOf(callback);
			if (idx >= 0) arr.splice(idx, 1);
		}
	}


	private _createRenderCallbackWrapper(array: OnRenderCallback[]): OnRenderCallback {
		return (renderer, scene, camera, geometry, material, group) => {
			for (let i = 0; i < array.length; i++) {
				const fn = array[i];
				fn(renderer, scene, camera, geometry, material, group);
			}
		}
	}



	private _requireDepthTexture: boolean = false;
	private _requireColorTexture: boolean = false;
	private _renderTarget?: WebGLRenderTarget;
	private _isRendering: boolean = false;

	/** @returns true while the WebGL renderer is rendering (between onBeforeRender and onAfterRender events) */
	get isRendering() { return this._isRendering; }

	setRequireDepth(val: boolean) {
		this._requireDepthTexture = val;
	}
	setRequireColor(val: boolean) {
		this._requireColorTexture = val;
	}
	get depthTexture(): DepthTexture | null {
		return this._renderTarget?.depthTexture || null;
	}
	get opaqueColorTexture(): Texture | null {
		return this._renderTarget?.texture || null;
	}

	/** @returns true if the `<needle-engine>` DOM element is visible on screen (`context.domElement`) */
	get isVisibleToUser() {
		if (this.isInXR) return true;
		if (!this._isVisible) return false;
		// Make sure not to call getComputedStyle multiple times per frame
		if (!this._needsVisibleUpdate && this._lastStyleComputedResult !== undefined) return this._lastStyleComputedResult;
		this._needsVisibleUpdate = false;
		const style = getComputedStyle(this.domElement);
		this._lastStyleComputedResult = style.visibility !== "hidden" && style.display !== "none" && style.opacity !== "0";
		return this._lastStyleComputedResult;
	}
	private _needsVisibleUpdate: boolean = true;
	private _lastStyleComputedResult: boolean | undefined = undefined;

	private _createId: number = 0;

	// #region internal create
	private async internalOnCreate(opts?: ContextCreateArgs): Promise<boolean> {
		const createId = ++this._createId;

		if (debug) console.log("Creating context", this.name, opts);

		// wait for async imported dependencies to be loaded
		// see https://linear.app/needle/issue/NE-4445
		const dependenciesReady = globalThis["needle:dependencies:ready"];
		if (dependenciesReady instanceof Promise) {
			if (debug) console.log("Waiting for dependencies to be ready");
			await dependenciesReady
				.catch(err => {
					if (debug || isDevEnvironment()) {
						showBalloonError("Needle Engine dependencies failed to load. Please check the console for more details");
						const printedError = false;
						if (err instanceof ReferenceError) {
							let offendingComponentName = "YourComponentName";
							const offendingComponentStartIndex = err.message.indexOf("'");
							if (offendingComponentStartIndex > 0) {
								const offendingComponentEndIndex = err.message.indexOf("'", offendingComponentStartIndex + 1);
								if (offendingComponentEndIndex > 0) {
									const name = err.message.substring(offendingComponentStartIndex + 1, offendingComponentEndIndex);
									if (name.length > 3) offendingComponentName = name;
								}
							}
							console.error(`Needle Engine dependencies failed to load:\n\n# Make sure you don't have circular imports in your scripts!\n\nPossible solutions: \n→ Replace @serializable(${offendingComponentName}) in your script with @serializable(Behaviour)\n→ If you only need type information try importing the type only, e.g: import { type ${offendingComponentName} }\n\n---`, err)
							return;
						}
						if (!printedError) {
							console.error("Needle Engine dependencies failed to load", err);
						}
					}
				})
				.then(() => {
					if (debug) console.log("Needle Engine dependencies are ready");
				});
		}

		this.clear();

		const oldRenderer = this.renderer;
		// We only need to create a new renderer if we don't have one yet
		// We do prevent creating a new renderer here to avoid flickering when the context is created while the content is still being loaded. 
		// This can be the case where CSS transformations update the layout (e.g. scale() while loading + old canvas disposed but in the DOM layout.)
		const needsNewRenderer = !oldRenderer || oldRenderer["isDisposed"] === true;

		// stop the animation loop if its running during creation
		// since we do not want to start enabling scripts etc before they are deserialized
		if (this.isManagedExternally === false && (needsNewRenderer)) {
			await this.createNewRenderer();
		}
		else {
			this.lodsManager.setRenderer(this.renderer);
		}
		this.renderer?.setAnimationLoop(null);

		Context.Current = this;
		await ContextRegistry.dispatchCallback(ContextEvent.ContextCreationStart, this);

		// load and create scene
		let prepare_succeeded = true;
		let loadedFiles!: Array<LoadedModel | null>;
		try {
			Context.Current = this;
			if (opts) {
				loadedFiles = await this.internalLoadInitialContent(createId, opts);
			}
			else loadedFiles = [];
		}
		catch (err) {
			console.error(err);
			prepare_succeeded = false;
		}
		if (!prepare_succeeded) {
			this.onError("Failed to load initial content");
			return false;
		}
		if (createId !== this._createId || opts?.abortSignal?.aborted) {
			return false;
		}

		this.internalOnUpdateVisible();

		if (!this.renderer) {
			if (debug) console.warn("Context has no renderer (perhaps it was disconnected?", this.domElement.isConnected);
			return false;
		}

		if (!this.isManagedExternally && !this.domElement.shadowRoot) {
			this.domElement.prepend(this.renderer.domElement);
		}

		Context.Current = this;

		// TODO: we could configure if we need physics
		// await this.physics.engine?.initialize();

		// Setup
		Context.Current = this;
		for (let i = 0; i < this.new_scripts.length; i++) {
			const script = this.new_scripts[i];
			if (script.gameObject !== undefined && script.gameObject !== null) {
				if (script.gameObject.userData === undefined) script.gameObject.userData = {};
				if (script.gameObject.userData.components === undefined) script.gameObject.userData.components = [];
				const arr = script.gameObject.userData.components;
				if (!arr.includes(script)) arr.push(script);
			}
			// if (script.gameObject && !this.raycastTargets.includes(script.gameObject)) {
			// 	this.raycastTargets.push(script.gameObject);
			// }
		}

		// const context = new SerializationContext(this.scene);
		// for (let i = 0; i < this.new_scripts.length; i++) {
		// 	const script = this.new_scripts[i];
		// 	const ser = script as unknown as ISerializable;
		// 	if (ser.$serializedTypes === undefined) continue;
		// 	context.context = this;
		// 	context.object = script.gameObject;
		// 	deserializeObject(ser, script, context);
		// }

		// resolve post setup callbacks (things that rely on threejs objects having references to components)
		if (this.post_setup_callbacks) {
			for (let i = 0; i < this.post_setup_callbacks.length; i++) {
				Context.Current = this;
				await this.post_setup_callbacks[i](this);
			}
		}

		if (!this._mainCamera) {
			Context.Current = this;
			let camera: ICamera | null = null;
			foreachComponent(this.scene, comp => {
				const cam = comp as ICamera;
				if (cam?.isCamera) {
					looputils.updateActiveInHierarchyWithoutEventCall(cam.gameObject);
					if (!cam.activeAndEnabled) return undefined;
					if (cam.tag === "MainCamera") {
						camera = cam;
						return true;
					}
					else camera = cam;
				}
				return undefined;
			});
			if (camera) {
				this.setCurrentCamera(camera);
			}
			else {
				const res = ContextRegistry.dispatchCallback(ContextEvent.MissingCamera, this, { files: loadedFiles });
				if (!res && !this.mainCamera && !this.isManagedExternally)
					console.warn("Missing camera in main scene", this);
			}
		}

		this.input.bindEvents();

		Context.Current = this;
		looputils.processNewScripts(this);

		// We have to step once so that colliders that have been created in onEnable can be raycasted in start
		if (this.physics.engine) {
			this.physics.engine?.step(0);
			this.physics.engine?.postStep();
		}

		// const mainCam = this.mainCameraComponent as Camera;
		// if (mainCam) {
		// 	mainCam.applyClearFlagsIfIsActiveCamera();
		// }

		if (!this.isManagedExternally && this.composer && this.mainCamera) {
			// TODO: import postprocessing async
			// const renderPass = new RenderPass(this.scene, this.mainCamera);
			// this.renderer.setSize(this.domWidth, this.domHeight);
			// this.composer.addPass(renderPass);
			// this.composer.setSize(this.domWidth, this.domHeight);
		}

		this._needsUpdateSize = true;

		if (this._stats) {
			this._stats.showPanel(0);
			this._stats.dom.style.position = "absolute"; // (default is fixed)
			this.domElement.shadowRoot?.appendChild(this._stats.dom);
		}

		if (debug)
			logHierarchy(this.scene, true);

		// If no target framerate was set we use the default
		if (this.targetFrameRate === undefined) {
			if (debug) console.warn("No target framerate set, using default", Context.DefaultTargetFrameRate);
			// the _defaultTargetFramerate is intentionally an object so it can be changed at any time if not explictly set by the user
			this.targetFrameRate = Context._defaultTargetFramerate;
		}
		else if (debug) console.log("Target framerate set to", this.targetFrameRate);

		this._dispatchReadyAfterFrame = true;
		const res = ContextRegistry.dispatchCallback(ContextEvent.ContextCreated, this, { files: loadedFiles });
		if (res) {
			const domElement = this.domElement as HTMLElement;
			if ("internalSetLoadingMessage" in domElement && typeof domElement.internalSetLoadingMessage === "function")
				domElement?.internalSetLoadingMessage("finish loading");
			await res;
		}
		if (opts?.abortSignal?.aborted) {
			return false;
		}


		const mainIdentifier = this.rootSourceId;
		if (mainIdentifier) this.sceneLighting.enable(mainIdentifier);

		invokeLifecycleFunctions(this, ContextEvent.ContextCreated);
		if (debug) console.log("Context Created...", this.renderer, this.renderer.domElement)

		this._isCreating = false;
		if (!this.isManagedExternally && !opts?.abortSignal?.aborted)
			this.restartRenderLoop();
		return true;
	}


	/** content state (like addressables/lightmaps) — self-managed by internalLoadInitialContent, not reset */
	@resettable("keep") private readonly rootSceneSourceIdentifiers: SourceIdentifier[] = [];
	private async internalLoadInitialContent(createId: number, args: ContextCreateArgs): Promise<Array<LoadedModel>> {
		this.rootSceneSourceIdentifiers.length = 0;

		const results = new Array<LoadedModel>();
		// early out if we dont have any files to load
		if (args.files.length === 0) return results;

		const files = [...args.files];
		this.rootSceneSourceIdentifiers.push(...files);

		const progressArg: LoadingProgressArgs = {
			name: "",
			progress: null!,
			index: 0,
			count: files.length
		}


		const loader = getLoader();
		// this hash should be constant since it is used to initialize the UIDProvider per initially loaded scene
		const loadingHash = 0;
		for (let i = 0; i < files.length; i++) {
			if (args.abortSignal?.aborted) {
				if (debug) console.log("Aborting loading because of abort signal");
				break;
			}
			// abort loading if the create id has changed
			if (createId !== this._createId) {
				if (debug) console.log("Aborting loading because create id changed", createId, this._createId);
				break;
			}
			const file = files[i];
			args?.onLoadingStart?.call(this, i, file);
			if (debug) console.log("Context Load " + file);
			const res = await loader.loadSync(this, file, file, loadingHash, prog => {
				if (args.abortSignal?.aborted) return;
				progressArg.name = file;
				progressArg.progress = prog;
				progressArg.index = i;
				progressArg.count = files.length;
				args.onLoadingProgress?.call(this, progressArg);
			});
			args?.onLoadingFinished?.call(this, i, file, res ?? null);
			if (res) {
				results.push({
					src: file,
					file: res
				});
			}
			else {
				// a file could not be loaded
				console.warn("Could not load file: " + file);
			}
		}

		// if the id was changed while still loading
		// then we want to cleanup/destroy previously loaded files
		if (createId !== this._createId || args.abortSignal?.aborted) {
			if (debug) console.log("Aborting loading because create id changed or abort signal was set", createId, this._createId);
			for (const res of results) {
				if (res && res.file) {
					for (const scene of res.file.scenes)
						destroy(scene, true, true);
				}
			}
		}
		// otherwise we want to add the loaded files to the current scene
		else {
			let anyModelFound = false;
			for (const res of results) {
				if (res && res.file) {
					// TODO: should we load all scenes in a glTF here?
					if (res.file.scene) {
						anyModelFound = true;
						this.scene.add(res.file.scene);
					}
					else {
						console.warn("No scene found in loaded file");
					}
				}
			}
			// If the loaded files do not contain ANY model
			// We then attempt to create a mesh from each material in the loaded files to visualize it
			// It's ok to do this at this point because we know the context has been cleared because the whole `src` attribute has been set
			if (!anyModelFound) {
				for (const res of results) {
					if (res && res.file && "parser" in res.file) {
						if (!Array.isArray(res.file.parser.json.materials)) continue;
						// Collect the generated shaderballs under a single root so we can
						// surface it as the loaded file's `scene` (see below). Without this
						// the shaderball is only present in the context scene while
						// `file.scene` stays undefined — then anything keyed off the loaded
						// file (bounds caching, ground projection, auto-fit, ContextCreated
						// `files` consumers) can neither see nor place it.
						const root = new Group();
						root.name = "Material Preview";
						let y = 0;
						for (let i = 0; i < res.file.parser.json.materials.length; i++) {
							const mat = await res.file.parser.getDependency("material", i);
							const parent = new Object3D();
							parent.position.x = i * 1.1;
							parent.position.y = y;
							root.add(parent);
							ObjectUtils.createPrimitive("ShaderBall", {
								parent,
								material: mat
							});
						}
						y += 1;
						// Surface the generated preview as the file's scene so it is treated
						// like any other loaded model root, and add it to the scene.
						res.file.scene = root;
						res.file.scenes = [root];
						this.scene.add(root);
					}
				}
			}
		}

		return results;
	}


	/** Sets the animation loop.   
	 * Can not be done while creating the context or when disposed 
	 **/
	public restartRenderLoop(): boolean {
		if (!this.renderer) {
			console.error("Can not start render loop without renderer");
			return false;
		}
		if (this._isCreating) {
			console.warn("Can not start render loop while creating context");
			return false;
		}
		this.renderer.setAnimationLoop((timestamp, frame: XRFrame | null) => {
			if (this.isManagedExternally) return;
			this.update(timestamp, frame)
		});
		return true;
	}

	private _renderlooperrors = 0;

	/** Performs a full update step including script callbacks, rendering (unless isManagedExternally is set to false) and post render callbacks */
	public update(timestamp: DOMHighResTimeStamp, frame?: XRFrame | null) {
		if (frame === undefined) frame = null;
		if (isDevEnvironment() || debug || looputils.hasNewScripts()) {
			try {
				//performance.mark('update.start');
				this.internalStep(timestamp, frame);
				this._renderlooperrors = 0;
				//performance.mark('update.end');
				//performance.measure('NE Frame', 'update.start', 'update.end');
			}
			catch (err) {
				this._renderlooperrors += 1;
				if ((isDevEnvironment() || debug) && (err instanceof Error || err instanceof TypeError))
					showBalloonMessage(`Caught unhandled exception during render-loop - see console for details.`, { type: LogType.Error });
				console.error("Frame #" + this.time.frame + "\n", err);
				if (this._renderlooperrors >= 3) {
					console.warn("Stopping render loop due to error")
					this.renderer.setAnimationLoop(null);
					Telemetry.sendError(Context.Current, "renderloop", err instanceof Error ? err : new Error(String(err)));
				}
				this.domElement.dispatchEvent(new CustomEvent("error", { detail: err }));
			}
		}
		else {
			this.internalStep(timestamp, frame);
		}
	}

	/** Call to **manually** perform physics steps.   
	 * By default the context uses the `physicsSteps` property to perform steps during the update loop   
	 * If you just want to increase the accuracy of physics you can instead set the `physicsSteps` property to a higher value
	 * */
	public updatePhysics(steps: number) {
		this.internalUpdatePhysics(steps);
	}



	/**
	 * Set a rect or dom element. The camera center will be moved to the center of the rect.  
	 * This is useful if you have Needle Engine embedded in a HTML layout and while you want the webgl background to fill e.g. the whole screen you want to move the camera center to free space.  
	 * For that you can simply pass in the rect or HMTL div that you want the camera to center on.
	 * @param rect The focus rect or null to disable
	 * @param settings Optional settings for the focus rect. These will override the `focusRectSettings` property
	 */
	public setCameraFocusRect(rect: FocusRect | null, settings?: Partial<FocusRectSettings>) {
		const oldRect = this._focusRect;
		this._focusRect = rect;
		if (settings) {
			Object.assign(this.focusRectSettings, settings);
		}
		if (settings?.damping === undefined) {
			// if the new rect is on screen then set damping
			if (oldRect) {
				let domRect = oldRect as DOMRect;
				if (oldRect instanceof HTMLElement) {
					domRect = oldRect.getBoundingClientRect();
				}
				if (domRect && "top" in domRect) {
					const allowedDistance = 100;
					const isVisible = domRect.bottom >= -allowedDistance && domRect.right >= -allowedDistance && domRect.top <= window.innerHeight + allowedDistance && domRect.left <= window.innerWidth + allowedDistance;
					if (isVisible) this.focusRectSettings.damping = .2;
				}
			}
		}

	}
	get focusRect() { return this._focusRect; }
	get focusRectSize(): null | { x: number, y: number, width: number, height: number } {
		const rect = this._focusRect;
		if (rect && (rect instanceof DOMRect || ("width" in rect && "height" in rect && "x" in rect && "y" in rect))) {
			return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
		}
		else if (rect instanceof HTMLElement) {
			const r = rect.getBoundingClientRect();
			return { x: r.x, y: r.y, width: r.width, height: r.height };
		}
		return null;
	}
	/** Settings when a focus rect is set. Use `setCameraFocusRect(...)` to do so.  
	 * This can be used to offset the renderer center e.g. to a specific DOM element.
	 */
	readonly focusRectSettings: FocusRectSettings = {
		/** Controls how fast the rect is centered. Smaller values mean the rect is centered faster.   
		 * A minimum value of 0 means the rect is centered instantly.
		 * @default 0
		*/
		damping: 0,

		/**
		 * Zoom factor when a focus rect is set.
		 */
		zoom: 1,
		/**
		 * Additional offset in pixels from the center of the rect
		 */
		offsetX: 0,
		/**
		 * Additional offset in pixels from the center of the rect
		 */
		offsetY: 0,
	};
	private _focusRect: FocusRect | null = null;


	private _lastTimestamp = 0;
	private _accumulatedTime = 0;
	private _dispatchReadyAfterFrame = false;

	// TODO: we need to skip after render callbacks if the render loop is managed externally. When changing this we also need to to update the r3f sample
	private internalStep(timestamp: DOMHighResTimeStamp, frame: XRFrame | null) {
		if (this.internalOnBeforeRender(timestamp, frame) === false) return;
		this.internalOnRender();
		this.internalOnAfterRender();
	}

	private internalOnBeforeRender(timestamp: DOMHighResTimeStamp, frame: XRFrame | null) {
		if (this.frameBegin(timestamp, frame) === false) return false;

		// While the lifecycle is held the frame still renders through the full pipeline,
		// but no component lifecycle advances: nothing awakes, enables, starts or updates,
		// no coroutines run and physics doesn't step. Queued components stay queued.
		const lifecycleHeld = this._lifecycle === "held";
		if (!lifecycleHeld) {
			this.processLifecycle();
			this.updateScripts();
			this.stepPhysicsDefault();
		}
		else {
			// loading finalization is data integrity, not simulation: glTF loading defers
			// component reference resolution into the pre-setup queue — without this,
			// content loaded into a held context keeps raw unresolved reference data
			looputils.processPreSetupCallbacks(this);
		}
		this.preRender(frame, lifecycleHeld);

		return true;
	}

	/** Frame prologue: renderer stats, XR frame bookkeeping, framerate limiting, pause
	 * handling and time update. Returns false if the frame should be skipped entirely. */
	private frameBegin(timestamp: DOMHighResTimeStamp, frame: XRFrame | null): boolean {

		// A context that is being updated must have working input: hosts that construct a
		// Context with their own renderer and never call create() would otherwise have no
		// engine pointer events at all (input.bindEvents only runs in the engine's own boot
		// paths). Bound lazily here; hosts opt out via input.unbindEvents(), which sticks.
		if (!this.input.eventsBound && !this.input.eventsExplicitlyUnbound) {
			this.input.bindEvents();
		}

		// If we don't auto reset we get wrong stats in WebXR. AutoReset was turned off to support custom blits and count them too
		// But when we're using postprocessing we need to reset manually: https://discourse.threejs.org/t/accessing-draw-calls-when-using-effectcomposer
		this.renderer.info.autoReset = frame ? true : false;
		if (this.renderer.info.autoReset === false) {
			this.renderer.info.reset();
		}

		this._needsVisibleUpdate = true;

		const sessionStarted = frame !== null && this._xrFrame === null;
		this._xrFrame = frame;
		if (sessionStarted) {
			this.domElement.dispatchEvent(new CustomEvent("xr-session-started", { detail: { context: this, session: this.xrSession, frame: frame } }));
		}

		this._currentFrameEvent = FrameEvent.Undefined;

		if (this.isManagedExternally === false && this.isInXR === false && this.targetFrameRate !== undefined) {
			if (this._lastTimestamp === 0) this._lastTimestamp = timestamp;
			this._accumulatedTime += (timestamp - this._lastTimestamp) / 1000;
			this._lastTimestamp = timestamp;
			let targetFrameRate = this.targetFrameRate;
			if (typeof targetFrameRate === "object") targetFrameRate = targetFrameRate.value!;
			// if(debug) console.log(this._accumulatedTime, (1 / (targetFrameRate)))
			if (this._accumulatedTime < (1 / (targetFrameRate + 1))) {
				return false;
			}
			this._accumulatedTime = 0;
		}

		this._stats?.begin();

		Context.Current = this;
		if (this.onHandlePaused()) return false;

		Context.Current = this;
		this.time.update();

		if (debugframerate) console.log("FPS", (this.time.smoothedFps).toFixed(0));

		return true;
	}

	/** Processes newly added components (awake/onEnable), hierarchy active-state changes
	 * and the start queue. Skipped while {@link lifecycle} is held. */
	private processLifecycle() {
		looputils.processNewScripts(this);
		looputils.updateIsActive(this.scene);
		looputils.processStart(this);
		invokeLifecycleFunctions(this, FrameEvent.Start);
	}

	/** Per-frame simulation: camera-stack cleanup, pre-update callbacks and the
	 * earlyUpdate/update/lateUpdate script loops including their coroutines.
	 * Skipped while {@link lifecycle} is held. */
	private updateScripts() {
		while (this._cameraStack.length > 0 && (!this.mainCameraComponent || this.mainCameraComponent.destroyed)) {
			this._cameraStack.splice(this._cameraStack.length - 1, 1);
			const last = this._cameraStack[this._cameraStack.length - 1];
			this.setCurrentCamera(last);
		}

		if (this.pre_update_oneshot_callbacks) {
			for (const i in this.pre_update_oneshot_callbacks) {
				this.pre_update_oneshot_callbacks[i]();
			}
			this.pre_update_oneshot_callbacks.length = 0;
		}

		if (this.pre_update_callbacks) {
			for (const i in this.pre_update_callbacks) {
				this.pre_update_callbacks[i]();
			}
		}

		this._currentFrameEvent = FrameEvent.EarlyUpdate;

		for (let i = 0; i < this.scripts_earlyUpdate.length; i++) {
			const script = this.scripts_earlyUpdate[i];
			if (!script.activeAndEnabled) continue;
			if (script.earlyUpdate !== undefined) {
				Context.Current = this;
				script.earlyUpdate();
			}
		}
		this.executeCoroutines(FrameEvent.EarlyUpdate);
		invokeLifecycleFunctions(this, FrameEvent.EarlyUpdate);

		this._currentFrameEvent = FrameEvent.Update;

		for (let i = 0; i < this.scripts_update.length; i++) {
			const script = this.scripts_update[i];
			if (!script.activeAndEnabled) continue;
			if (script.update !== undefined) {
				Context.Current = this;
				script.update();
			}
		}
		this.executeCoroutines(FrameEvent.Update);
		invokeLifecycleFunctions(this, FrameEvent.Update);
		this._currentFrameEvent = FrameEvent.LateUpdate;

		for (let i = 0; i < this.scripts_lateUpdate.length; i++) {
			const script = this.scripts_lateUpdate[i];
			if (!script.activeAndEnabled) continue;
			if (script.lateUpdate !== undefined) {
				Context.Current = this;
				script.lateUpdate();
			}
		}

		// this.mainLight = null;
		this.executeCoroutines(FrameEvent.LateUpdate);
		invokeLifecycleFunctions(this, FrameEvent.LateUpdate);
	}

	/** Default physics stepping using {@link physicsSteps}. Skipped while {@link lifecycle} is held. */
	private stepPhysicsDefault() {
		if (this.physicsSteps === undefined) {
			this.physicsSteps = 1;
		}
		if (this.physics.engine && this.physicsSteps > 0) {
			this.internalUpdatePhysics(this.physicsSteps);
		}
	}

	/** Pre-render section. Render infrastructure (pending size updates, pre-render callbacks,
	 * focus rect) always runs; the onBeforeRender script callbacks, coroutines and lifecycle
	 * functions are skipped while {@link lifecycle} is held. */
	private preRender(frame: XRFrame | null, skipScripts: boolean) {
		if (this.isVisibleToUser || this.runInBackground) {

			this._currentFrameEvent = FrameEvent.OnBeforeRender;

			if (!skipScripts) {
				// should we move these callbacks in the regular three onBeforeRender events?
				for (let i = 0; i < this.scripts_onBeforeRender.length; i++) {
					const script = this.scripts_onBeforeRender[i];
					if (!script.activeAndEnabled) continue;
					// if(script.isActiveAndEnabled === false) continue;
					if (script.onBeforeRender !== undefined) {
						Context.Current = this;
						script.onBeforeRender(frame);
					}
				}

				this.executeCoroutines(FrameEvent.OnBeforeRender);
				invokeLifecycleFunctions(this, FrameEvent.OnBeforeRender);
			}

			if (this._needsUpdateSize)
				this.updateSize();

			if (this.pre_render_callbacks) {
				for (const i in this.pre_render_callbacks) {
					this.pre_render_callbacks[i](frame);
				}
			}

			if (this._focusRect) {
				if (this.mainCamera instanceof PerspectiveCamera) {
					const settings = this.focusRectSettings;
					const dt = settings.damping > 0 ? this.time.deltaTime / settings.damping : 1;
					updateCameraFocusRect(this._focusRect, this.focusRectSettings, dt, this.mainCamera, this.renderer);
				}
			}

		}
	}

	private internalUpdatePhysics(steps: number) {
		if (!this.physics.engine) return false;
		const physicsSteps = steps;
		const dt = this.time.deltaTime / physicsSteps;
		for (let i = 0; i < physicsSteps; i++) {
			this._currentFrameEvent = FrameEvent.PrePhysicsStep;
			this.executeCoroutines(FrameEvent.PrePhysicsStep);
			this.physics.engine.step(dt);
			this._currentFrameEvent = FrameEvent.PostPhysicsStep;
			this.executeCoroutines(FrameEvent.PostPhysicsStep);
		}
		this.physics.engine.postStep();
		return true;
	}

	private internalOnRender() {
		if (!this.isManagedExternally) {
			// when loading assets we compile them async after GLTFLoader is done
			// but as a fallback we still register them (if e.g. there's no camera for compile async)
			looputils.runPrewarm(this);
			this._currentFrameEvent = FrameEvent.Undefined;
			nodeFrame.camera = this.mainCamera as Camera | null;
			nodeFrame.update();
			this.renderNow();
			this._currentFrameEvent = FrameEvent.OnAfterRender;
		}
	}

	private internalOnAfterRender() {
		if (this.isVisibleToUser || this.runInBackground) {
			if (this._lifecycle !== "held") {
				for (let i = 0; i < this.scripts_onAfterRender.length; i++) {
					const script = this.scripts_onAfterRender[i];
					if (!script.activeAndEnabled) continue;
					if (script.onAfterRender !== undefined) {
						Context.Current = this;
						script.onAfterRender();
					}
				}

				this.executeCoroutines(FrameEvent.OnAfterRender);
				invokeLifecycleFunctions(this, FrameEvent.OnAfterRender);
			}

			if (this.post_render_callbacks) {
				for (const i in this.post_render_callbacks) {
					this.post_render_callbacks[i]();
				}
			}
		}

		this._currentFrameEvent = -1;

		this.connection.sendBufferedMessagesNow();

		if (this._stats) {
			this._stats.end();
			const dt = this.time.fps < 20 ? 50 : 150;
			if (this.time.frameCount % dt === 0 || this.time.frameCount === 1) {
				const usedJSHeapSize = window.performance && (window.performance as any).memory
					? (`${((window.performance as any).memory.usedJSHeapSize / 1024 / 1024).toFixed(2)} MB`)
					: "n/a";

				const gl = this.renderer.getContext();
				console.log(this.renderer.info.render.calls + " DrawCalls", "\nRender:",
					{
						shaders: this.renderer.info.programs?.length,
						...this.renderer.info.render,
					},
					"\nMemory:",
					{
						usedMemory: usedJSHeapSize,
						...this.renderer.info.memory
					},
					"\nRenderer:",
					{
						dpr: this.renderer.getPixelRatio(),
						windowDpr: window.devicePixelRatio,
						antialias: gl.getContextAttributes()?.antialias,
						samples: gl.getParameter(gl.SAMPLES),
						resolution: `${this.renderer.domElement.width}x${this.renderer.domElement.height}`,
					},
					"\nTarget Framerate: " + this.targetFrameRate);
			}
		}

		if (this._dispatchReadyAfterFrame) {
			this._dispatchReadyAfterFrame = false;
			this.domElement.dispatchEvent(new CustomEvent("ready"));
			ContextRegistry.dispatchCallback(ContextEvent.ContextFirstFrameRendered, this);
		}
	}

	private readonly _tempClearColor = new Color();
	private readonly _tempClearColor2 = new Color();
	renderNow(camera?: Camera) {
		if (!camera) {
			camera = this.mainCamera as Camera;
			if (!camera) return false;
		}
		this.handleRendererContextLost();

		this._isRendering = true;
		this.renderRequiredTextures();

		if (this.renderer.toneMapping !== NoToneMapping)
			patchTonemapping(this);

		// Update postprocessing stack (applies dirty effects, adaptive multisampling/pixel ratio)
		this.postprocessing.update();

		if (this.composer && !this.isInXR) {
			// if a camera is passed in we need to check if we need to update the composer's camera
			if (camera && "setMainCamera" in this.composer) {
				const currentPassesCamera = this.composer.passes[0]?.mainCamera;
				if (currentPassesCamera != camera)
					this.composer.setMainCamera(camera);
			}

			const backgroundColor = this.renderer.getClearColor(this._tempClearColor);
			const clearAlpha = this.renderer.getClearAlpha();
			this._tempClearColor2.copy(backgroundColor);
			this.renderer.setClearColor(backgroundColor.convertSRGBToLinear(), this.renderer.getClearAlpha());
			this.composer.render(this.time.deltaTime);
			this.renderer.setClearColor(this._tempClearColor2, clearAlpha); // restore clear color
		}
		else if (camera) {
			// Workaround for issue on Vision Pro – 
			// depth buffer is not cleared between eye draws, despite the spec...
			if (this.isInXR && DeviceUtilities.isMacOS())
				this.renderer.clearDepth();
			this.renderer.render(this.scene, camera);
		}
		this._isRendering = false;
		return true;
	}

	private _contextRestoreTries = 0;
	private handleRendererContextLost() {
		// Try to restore the context every x frames
		if (this.time.frame % 10 && this.renderer.getContext().isContextLost()) {
			if (this._contextRestoreTries++ < 100) {
				console.warn("Attempting to recover WebGL context...");
				this.renderer.forceContextRestore();
			}
		}
	}

	/** returns true if we should return out of the frame loop */
	private _wasPaused: boolean = false;
	private onHandlePaused(): boolean {
		const paused = this.evaluatePaused();
		if (this._wasPaused !== paused) {
			if (debugActive) console.log("Paused?", paused, "context:" + this.alias);
			for (let i = 0; i < this.scripts_pausedChanged.length; i++) {
				const script = this.scripts_pausedChanged[i];
				if (!script.activeAndEnabled) continue;
				if (script.onPausedChanged !== undefined) {
					Context.Current = this;
					script.onPausedChanged(paused, this._wasPaused);
				}
			}
		}
		this._wasPaused = paused;
		return paused;
	}

	private evaluatePaused(): boolean {
		if (this.isInXR) return false;
		if (this.isPaused) return true;
		// if the element is not visible use the runInBackground flag to determine if we should continue
		if (this.runInBackground) {
			return false;
		}
		const paused = !this.isVisibleToUser;
		return paused;
	}

	private renderRequiredTextures() {
		if (!this.mainCamera) return;
		if (!this._requireDepthTexture && !this._requireColorTexture) return;
		if (!this._renderTarget) {
			this._renderTarget = new WebGLRenderTarget(this.domWidth, this.domHeight);
			if (this._requireDepthTexture) {
				const dt = new DepthTexture(this.domWidth, this.domHeight);;
				this._renderTarget.depthTexture = dt;
			}
			if (this._requireColorTexture) {
				this._renderTarget.texture = new Texture();
				this._renderTarget.texture.generateMipmaps = false;
				this._renderTarget.texture.minFilter = NearestFilter;
				this._renderTarget.texture.magFilter = NearestFilter;
				this._renderTarget.texture.format = RGBAFormat;
			}
		}
		const rt = this._renderTarget;
		if (rt.texture) {
			rt.texture.colorSpace = this.renderer.outputColorSpace;
		}
		const prevTarget = this.renderer.getRenderTarget();
		this.renderer.setRenderTarget(rt);
		this.renderer.render(this.scene, this.mainCamera);
		this.renderer.setRenderTarget(prevTarget);
	}

	private executeCoroutines(evt: FrameEvent) {
		if (this.coroutines[evt]) {
			const evts = this.coroutines[evt];
			for (let i = 0; i < evts.length; i++) {
				try {
					const evt = evts[i];
					// TODO we might want to keep coroutines playing even if the component is disabled or inactive
					const remove = !evt.comp || evt.comp.destroyed || !evt.main || evt.comp["enabled"] === false;
					if (remove) {
						if (debugCoroutine) console.log("Removing coroutine", evt.comp, evt.comp["enabled"])
						evts.splice(i, 1);
						--i;
						continue;
					}
					const iter = evt.chained;
					if (iter && iter.length > 0) {
						const last: Generator = iter[iter.length - 1];
						const res = last.next();
						if (res.done) {
							iter.pop();
						}
						if (isGenerator(res)) {
							if (!evt.chained) evt.chained = [];
							evt.chained.push(res.value);
						}
						if (!res.done) continue;
					}

					const res = evt.main.next();
					if (res.done === true) {
						evts.splice(i, 1);
						--i;
						continue;
					}
					const val = res.value;
					if (isGenerator(val)) {
						// invoke once if its a generator
						// this means e.g. WaitForFrame(1) works and will capture
						// the frame it was created
						const gen = val as Generator;
						const res = gen.next();
						if (res.done) continue;
						if (!evt.chained) evt.chained = [];
						evt.chained.push(val as Generator);
					}
					else if (val instanceof Promise) {
						// If its a promise we want to wait for it to resolve
						const prom = val as Promise<any>;
						if (!evt.chained) evt.chained = [];
						const nested = WaitForPromise(prom);
						evt.chained?.push(nested);
						continue;
					}
				}
				catch (e) {
					console.error(e);
				}
			}
		}

		function isGenerator(val: any): boolean {
			if (val) {
				if (val.next && val.return) {
					return true;
				}
			}
			return false;
		}
	}

}


// const scene = new Scene();
// const useComposer = utils.getParam("postfx");
// const renderer = new WebGLRenderer({ antialias: true });
// const composer = useComposer ? new EffectComposer(renderer) : undefined;

// renderer.setClearColor(new Color('lightgrey'), 0)
// renderer.antialias = true;
// renderer.alpha = false;
// renderer.shadowMap.enabled = true;
// renderer.shadowMap.type = PCFSoftShadowMap;
// renderer.setSize(window.innerWidth, window.innerHeight);
// renderer.outputEncoding = sRGBEncoding;
// renderer.physicallyCorrectLights = true;
// document.body.appendChild(renderer.domElement);

// // generation pushes loading requests in this array
// const sceneData: {
//     mainCamera: Camera | undefined
// } = {
//     preparing: [],
//     resolving: [],
//     scripts: [],
//     raycastTargets: [],
//     mainCamera: undefined,
//     mainCameraComponent: undefined,
// };

// // contains a list of functions to be called after loading is done
// const post_setup_callbacks = [];

// const pre_render_Callbacks = [];
// const post_render_callbacks = [];

// const new_scripts = [];
// const new_scripts_post_setup_callbacks = [];
// const new_scripts_pre_setup_callbacks = [];

// export {
//     scene, renderer, composer,
//     new_scripts,
//     new_scripts_post_setup_callbacks, new_scripts_pre_setup_callbacks,
//     sceneData,
//     post_setup_callbacks,
//     pre_render_Callbacks,
//     post_render_callbacks
// }