@needle-tools/engine 3.28.6-beta → 3.28.7-beta.1

package/src/engine-components/SceneSwitcher.ts

@@ -1,594 +1,594 @@
-import { AssetReference } from "../engine/engine_addressables.js";
-import { InputEvents } from "../engine/engine_input.js";
-import { isLocalNetwork } from "../engine/engine_networking_utils.js";
-import { delay, getParam, setParamWithoutReload } from "../engine/engine_utils.js";
-import { serializable } from "../engine/engine_serialization.js";
-import { Behaviour, GameObject } from "./Component.js";
-import { registerObservableAttribute } from "../engine/engine_element_extras.js";
-import { Object3D } from "three";
-
-const debug = getParam("debugsceneswitcher");
-
-const ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME = "scene";
-registerObservableAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
-
-// ContextRegistry.registerCallback(ContextEvent.ContextRegistered, async _ => {
-//     // We need to defer import to not get issues with circular dependencies
-//     import("../engine/engine_element").then(res => {
-//         const webcomponent = res.NeedleEngineHTMLElement;
-//         if (debug) console.log("SceneSwitcher: registering scene attribute", webcomponent.observedAttributes);
-//         if (!webcomponent.observedAttributes.includes(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME))
-//             webcomponent.observedAttributes.push(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
-//     });
-// });
-
-const couldNotLoadScenePromise = Promise.resolve(false);
-
-export type LoadSceneEvent = {
-    switcher: SceneSwitcher;
-    scene: AssetReference;
-    index: number;
-}
-
-/** The ISceneEventListener is called by the SceneSwitcher when a scene is loaded or unloaded. It must be added to the root object of your scene */
-export interface ISceneEventListener {
-    /** Called when the scene is loaded and added */
-    sceneOpened?(): Promise<void>
-    /** Called before the scene is being removed (due to another scene being loaded) */
-    sceneClosing?(): Promise<void>
-}
-
-export class SceneSwitcher extends Behaviour {
-
-    @serializable(AssetReference)
-    scenes!: AssetReference[];
-
-    @serializable(AssetReference)
-    loadingScene!: AssetReference;
-
-    /** the url parameter that is set/used to store the currently loaded scene in, set to "" to disable */
-    @serializable()
-    queryParameterName: string = "scene";
-
-    /** 
-     * when enabled the scene name will be used as the query parameter (otherwise the scene index will be used)
-     * Needs `queryParameterName` set
-     * */
-    @serializable()
-    useSceneName: boolean = true;
-
-    @serializable()
-    clamp: boolean = true;
-
-    /** when enabled the new scene is pushed to the browser navigation history, only works with a valid query parameter set */
-    @serializable()
-    useHistory: boolean = true;
-
-    /** when enabled you can switch between scenes using keyboard left, right, A and D or number keys */
-    @serializable()
-    useKeyboard: boolean = true;
-
-    /** when enabled you can switch between scenes using swipe (mobile only) */
-    @serializable()
-    useSwipe: boolean = true;
-
-    /** when enabled will automatically apply the environment scene lights */
-    @serializable()
-    useSceneLighting: boolean = true;
-
-    /** how many scenes after the currently active scene should be preloaded */
-    @serializable()
-    preloadNext: number = 1;
-
-    /** how many scenes before the currently active scene should be preloaded */
-    @serializable()
-    preloadPrevious: number = 1;
-
-    /** how many scenes can be loaded in parallel */
-    @serializable()
-    preloadConcurrent: number = 2;
-
-
-    get currentIndex(): number { return this._currentIndex; }
-
-    private _currentIndex: number = -1;
-    private _currentScene: AssetReference | undefined = undefined;
-    private _engineElementOverserver: MutationObserver | undefined = undefined;
-
-    private _preloadScheduler?: PreLoadScheduler;
-
-    awake(): void {
-        if (debug) console.log("SceneSwitcher", this);
-    }
-
-    async start() {
-        if (this._currentIndex === -1 && !await this.tryLoadFromQueryParam()) {
-            const value = this.context.domElement.getAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
-            // let locked = this.lock;
-            try {
-                // this.lock = false;
-                if (value === null || !await this.trySelectSceneFromValue(value)) {
-                    if (this._currentIndex === -1)
-                        this.select(0);
-                }
-            }
-            finally {
-                // this.lock = locked;
-            }
-        }
-    }
-
-    onEnable(): void {
-        globalThis.addEventListener("popstate", this.onPopState);
-        this.context.input.addEventListener(InputEvents.KeyDown, this.onKeyDown);
-        this.context.input.addEventListener(InputEvents.PointerMove, this.onPointerMove);
-        this.context.input.addEventListener(InputEvents.PointerUp, this.onPointerUp);
-
-        if (!this._engineElementOverserver) {
-            this._engineElementOverserver = new MutationObserver((mutations) => {
-                for (const mut of mutations) {
-                    if (mut.type === "attributes" && mut.attributeName === ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME) {
-                        const value = this.context.domElement.getAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
-                        if (value !== null) {
-                            this.trySelectSceneFromValue(value);
-                        }
-                    }
-                }
-            });
-        }
-
-        this._engineElementOverserver.observe(this.context.domElement, {
-            attributes: true
-        });
-
-        if (!this._preloadScheduler)
-            this._preloadScheduler = new PreLoadScheduler(this);
-        this._preloadScheduler.maxLoadAhead = this.preloadNext;
-        this._preloadScheduler.maxLoadBehind = this.preloadPrevious;
-        this._preloadScheduler.maxConcurrent = this.preloadConcurrent;
-        this._preloadScheduler.begin();
-
-        // Begin loading the loading scene
-        // if (this.loadingScene) this.loadingScene.loadAssetAsync();
-    }
-
-    onDisable(): void {
-        globalThis.removeEventListener("popstate", this.onPopState);
-        this.context.input.removeEventListener(InputEvents.KeyDown, this.onKeyDown);
-        this.context.input.removeEventListener(InputEvents.PointerMove, this.onPointerMove);
-        this.context.input.removeEventListener(InputEvents.PointerUp, this.onPointerUp);
-        this._preloadScheduler?.stop();
-    }
-
-    private onPopState = async (_state: PopStateEvent) => {
-        if (!this.useHistory) return;
-        const wasUsingHistory = this.useHistory;
-        try {
-            this.useHistory = false;
-            let didResolve = false;
-            if (this.queryParameterName)
-                didResolve = await this.tryLoadFromQueryParam();
-            if (!didResolve) {
-                const state = _state?.state;
-                if (state && state.startsWith(this.guid)) {
-                    const value = state.substr(this.guid.length + 2);
-                    if (debug) console.log("PopState", value);
-                    await this.trySelectSceneFromValue(value);
-                }
-            }
-        }
-        finally {
-            this.useHistory = wasUsingHistory;
-        }
-    }
-
-    private normalizedSwipeThresholdX = 0.1;
-    private _didSwipe: boolean = false;
-    private onPointerMove = (e: any) => {
-        if (!this.useSwipe) return;
-        if (!this._didSwipe && e.button === 0 && e.pointerType === "touch" && this.context.input.getPointerPressedCount() === 1) {
-            const delta = this.context.input.getPointerPositionDelta(e.button);
-            if (delta) {
-                const normalizedX = delta.x / this.context.domWidth;
-                if (normalizedX >= this.normalizedSwipeThresholdX) {
-                    this._didSwipe = true;
-                    this.selectPrev();
-                }
-                else if (normalizedX <= -this.normalizedSwipeThresholdX) {
-                    this._didSwipe = true;
-                    this.selectNext();
-                }
-            }
-        }
-    }
-
-    private onPointerUp = (e: any) => {
-        if (e.button === 0) {
-            this._didSwipe = false;
-        }
-    };
-
-    private onKeyDown = (e: any) => {
-        if (!this.useKeyboard) return;
-        if (!this.scenes) return;
-        const key = e.key.toLowerCase();
-        if (!key) return;
-        const index = parseInt(key) - 1;
-        if (index >= 0) {
-            this.trySelectSceneFromValue(index);
-            return;
-        }
-        switch (key) {
-            case "arrowright":
-            case "d":
-                this.selectNext();
-                break;
-            case "arrowleft":
-            case "a":
-                this.selectPrev();
-                break;
-        }
-    }
-
-    selectNext(): Promise<boolean> {
-        return this.select(this._currentIndex + 1);
-    }
-
-    selectPrev(): Promise<boolean> {
-        return this.select(this._currentIndex - 1);
-    }
-
-    select(index: number | string): Promise<boolean> {
-        if (debug) console.log("select", index);
-
-        if (typeof index === "object") {
-            // If a user tries to reference a scene object in a UnityEvent and invoke select(obj) 
-            // Then the object will be serialized as a object { guid : ... } or with the index json pointer
-            // This case is not supported right now. Object references in the editor must not be scene references
-            console.warn("Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
-        }
-
-        if (typeof index === "string") {
-            // If the parameter is a string we try to resolve the scene by its uri
-            // it's either already known in the scenes array
-            // or we create/get a new AssetReference and try to switch to that
-            const scene = this.scenes?.find(s => s.uri === index);
-            if (!scene) {
-                // Ok the scene is unknown to the scene switcher
-                // we create a new asset reference (or get an existing one)
-                // And switch to that. With this we can not modify the history
-                // Until the scene switcher can store the uri in the history instead of the index
-                const reference = AssetReference.getOrCreate(this.sourceId ?? "", index, this.context);
-                return this.switchScene(reference);
-            }
-            if (scene) index = this.scenes?.indexOf(scene);
-            else return couldNotLoadScenePromise;
-        }
-
-        if (!this.scenes?.length) return couldNotLoadScenePromise;
-        if (index < 0) {
-            if (this.clamp) return couldNotLoadScenePromise;
-            index = this.scenes.length - 1;
-        }
-        else if (index >= this.scenes.length) {
-            if (this.clamp) return couldNotLoadScenePromise;
-            index = 0;
-        }
-        const scene = this.scenes[index];
-        return this.switchScene(scene);
-    }
-
-
-    // this is the scene that was requested last
-    private __lastSwitchScene?: AssetReference;
-    private __lastSwitchScenePromise?: Promise<boolean>;
-
-    async switchScene(scene: AssetReference): Promise<boolean> {
-        if (!(scene instanceof AssetReference)) {
-            const type = typeof scene;
-            if (type === "string") {
-                return this.select(scene);
-            }
-            else if (type === "number") {
-                return this.select(scene);
-            }
-            else {
-                console.warn("SceneSwitcher: Can't switch to scene", scene, "of type", type);
-                return false;
-            }
-        }
-
-        // ensure that we never run the same scene switch multiple times (at the same time) for the same requested scene
-        if (this.__lastSwitchScene === scene && this.__lastSwitchScenePromise) {
-            return this.__lastSwitchScenePromise;
-        }
-        this.__lastSwitchScene = scene;
-        this.__lastSwitchScenePromise = this.__internalSwitchScene(scene);
-        const res = await this.__lastSwitchScenePromise;
-        return res;
-    }
-    async __internalSwitchScene(scene: AssetReference): Promise<boolean> {
-        if (this._currentScene) {
-            if (debug) console.log("UNLOAD", scene.uri)
-            const sceneListener = this.tryGetSceneEventListener(this._currentScene.asset as any as Object3D);
-            if (sceneListener?.sceneClosing) {
-                const res = sceneListener.sceneClosing();
-                if (res instanceof Promise) await res;
-            }
-            this._currentScene.unload();
-        }
-        this._currentScene = undefined;
-
-        const index = this._currentIndex = this.scenes?.indexOf(scene) ?? -1;
-        try {
-            const loadStartEvt = new CustomEvent<LoadSceneEvent>("loadscene-start", { detail: { scene: scene, switcher: this, index: index } })
-            this.dispatchEvent(loadStartEvt);
-            await this.onStartLoading();
-            await scene.loadAssetAsync().catch(console.error);
-            await this.onEndLoading();
-            const finishedEvt = new CustomEvent<LoadSceneEvent>("loadscene-finished", { detail: { scene: scene, switcher: this, index: index } });
-            this.dispatchEvent(finishedEvt);
-            if (finishedEvt.defaultPrevented) {
-                if (debug) console.warn("Adding loaded scene prevented:", scene, finishedEvt);
-                return false;
-            }
-            if (!scene.asset) {
-                if (debug) console.warn("Failed loading scene:", scene);
-                return false;
-            }
-            if (this._currentIndex === index) {
-                if (debug) console.log("ADD", scene.uri)
-                this._currentScene = scene;
-                GameObject.add(scene.asset, this.gameObject);
-                if (this.useSceneLighting)
-                    this.context.sceneLighting.enable(scene);
-                if (this.useHistory && index >= 0) {
-                    // take the index as the query parameter value
-                    let queryParameterValue = index.toString();
-                    // unless the user defines that he wants to use the scene name
-                    if (this.useSceneName) {
-                        queryParameterValue = sceneUriToName(scene.uri);
-                    }
-                    // save the loaded scene as an url parameter
-                    if (this.queryParameterName?.length)
-                        setParamWithoutReload(this.queryParameterName, queryParameterValue, this.useHistory);
-                    // or set the history state without updating the url parameter
-                    else {
-                        const lastState = history.state;
-                        const stateName = this.guid + "::" + index;
-                        if (lastState !== stateName)
-                            history.pushState(stateName, "unused", location.href);
-                    }
-                }
-                // Call SceneListener opened callback (if a SceneListener is in the scene)
-                const sceneListener = this.tryGetSceneEventListener(scene.asset as any as Object3D);
-                if (sceneListener?.sceneOpened) {
-                    const res = sceneListener.sceneOpened();
-                    if (res instanceof Promise) await res;
-                }
-                return true;
-            }
-        }
-        catch (err) {
-            console.error(err);
-        }
-        return false;
-    }
-
-    preload(index: number) {
-        if (index >= 0 && index < this.scenes.length) {
-            const scene = this.scenes[index];
-            if (scene instanceof AssetReference)
-                return scene.preload();
-        }
-        return couldNotLoadScenePromise;
-    }
-
-    private tryLoadFromQueryParam() {
-        if (!this.queryParameterName?.length) return couldNotLoadScenePromise;
-        // try restore the scene from the url
-        const value = getParam(this.queryParameterName);
-        if (typeof value === "boolean") return couldNotLoadScenePromise;
-        return this.trySelectSceneFromValue(value);
-    }
-
-    /** try to select a scene from a string or index */
-    private trySelectSceneFromValue(value: string | number) {
-
-        if (typeof value === "string") {
-            const index = parseInt(value as string);
-            if (index >= 0 && index < this.scenes.length) {
-                return this.select(index);;
-            }
-            else {
-                // Try to find a scene with a matching name
-                // we don't care about casing. e.g. Scene1 and scene1 should both match
-                const lowerCaseValue = value.toLowerCase();
-                for (let i = 0; i < this.scenes.length; i++) {
-                    const scene = this.scenes[i];
-                    if (!scene) continue;
-                    if (sceneUriToName(scene.uri).toLowerCase().includes(lowerCaseValue)) {
-                        return this.select(i);;
-                    }
-                }
-            }
-        }
-        else if (typeof value === "number") {
-            if (value >= 0 && value < this.scenes.length) {
-                return this.select(value);;
-            }
-        }
-
-        if (isLocalNetwork()) console.warn("Can not find scene: \"" + value + "\"", this)
-
-        return couldNotLoadScenePromise;
-    }
-
-    private _lastLoadingScene: AssetReference | undefined = undefined;
-    private _loadingScenePromise: Promise<boolean> | undefined = undefined;
-    private _isCurrentlyLoading: boolean = false;
-    private async onStartLoading() {
-        this._isCurrentlyLoading = true;
-        if (this.loadingScene) {
-            // save the last loading scene reference so that it can be changed at runtime
-            // since we cache the loading promise here
-            if(this._lastLoadingScene !== this.loadingScene) {
-                this._loadingScenePromise = undefined;
-            }
-            this._lastLoadingScene = this.loadingScene;
-            if (!this._loadingScenePromise) {
-                this._loadingScenePromise = this.loadingScene?.loadAssetAsync();
-            }
-            await this._loadingScenePromise;
-            if (this._isCurrentlyLoading && this.loadingScene?.asset) {
-                if (debug) console.log("Add loading scene", this.loadingScene.uri, this.loadingScene.asset)
-                const obj = this.loadingScene.asset as any as Object3D;
-                GameObject.add(obj, this.gameObject);
-                const sceneListener = this.tryGetSceneEventListener(obj);
-                if (sceneListener?.sceneOpened) {
-                    const res = sceneListener.sceneOpened();
-                    if (res instanceof Promise) await res;
-                }
-            }
-        }
-    }
-    private async onEndLoading() {
-        this._isCurrentlyLoading = false;
-        if (this.loadingScene?.asset) {
-            if (debug) console.log("Remove loading scene", this.loadingScene.uri);
-            const obj = this.loadingScene.asset as any as Object3D;
-            // try to find an ISceneEventListener component
-            const sceneListener = this.tryGetSceneEventListener(obj);
-            if (typeof sceneListener?.sceneClosing === "function") {
-                const res = sceneListener.sceneClosing();
-                if (res instanceof Promise) await res;
-            }
-            GameObject.remove(obj);
-        }
-    }
-
-    private tryGetSceneEventListener(obj: Object3D, level: number = 0): ISceneEventListener | null {
-        const sceneListener = GameObject.foreachComponent(obj, c => (c as any as ISceneEventListener).sceneClosing ? c : undefined) as ISceneEventListener | undefined;
-        // if we didnt find any component with the listener on the root object
-        // we also check the first level of its children because a scene might be a group
-        if (level === 0 && !sceneListener && obj.children.length) {
-            for (const ch of obj.children) {
-                const res = this.tryGetSceneEventListener(ch, level + 1);
-                if (res) return res;
-            }
-        }
-        if (!sceneListener) return null;
-        return sceneListener;
-    }
-}
-
-
-function sceneUriToName(uri: string): string {
-    const name = uri.split("/").pop();
-    const value = name?.split(".").shift();
-    if (value?.length) return value;
-    return uri;
-}
-
-
-
-class PreLoadScheduler {
-    maxLoadAhead: number;
-    maxLoadBehind: number;
-    maxConcurrent: number;
-
-    private _isRunning: boolean = false;
-    private _switcher: SceneSwitcher;
-    private _loadTasks: LoadTask[] = [];
-    private _maxConcurrentLoads: number = 1;
-
-    constructor(rooms: SceneSwitcher, ahead: number = 1, behind: number = 1, maxConcurrent: number = 2) {
-        this._switcher = rooms;
-        this.maxLoadAhead = ahead;
-        this.maxLoadBehind = behind;
-        this.maxConcurrent = maxConcurrent;
-    }
-
-    begin() {
-        if (this._isRunning) return;
-        if (debug) console.log("Preload begin")
-        this._isRunning = true;
-        let lastRoom: number = -1;
-        let searchDistance: number;
-        let searchCall: number;
-        const array = this._switcher.scenes;
-        const interval = setInterval(() => {
-            if (this.allLoaded()) {
-                if (debug)
-                    console.log("All scenes loaded");
-                this.stop();
-            }
-            if (!this._isRunning) {
-                clearInterval(interval);
-                return;
-            }
-            if (this.canLoadNewScene() === false) return;
-            if (lastRoom !== this._switcher.currentIndex) {
-                lastRoom = this._switcher.currentIndex;
-                searchCall = 0;
-                searchDistance = 0;
-            }
-            const searchForward = searchCall % 2 === 0;
-            if (searchForward) searchDistance += 1;
-            searchCall += 1;
-            const maxSearchDistance = searchForward ? this.maxLoadAhead : this.maxLoadBehind;
-            if (searchDistance > maxSearchDistance) return;
-            const roomIndex = searchForward ? lastRoom + searchDistance : lastRoom - searchDistance;
-            if (roomIndex < 0) return;
-            // if (roomIndex < 0) roomIndex = array.length + roomIndex;
-            if (roomIndex < 0 || roomIndex >= array.length) return;
-            const scene = array[roomIndex];
-            new LoadTask(roomIndex, scene, this._loadTasks);
-        }, 200);
-    }
-
-    stop() {
-        this._isRunning = false;
-    }
-
-    canLoadNewScene(): boolean {
-        return this._loadTasks.length < this._maxConcurrentLoads;
-    }
-
-    allLoaded(): boolean {
-        if (this._switcher.scenes) {
-            for (const scene of this._switcher.scenes) {
-                if (scene?.isLoaded() === false) return false;
-            }
-        }
-        return true;
-    }
-}
-
-class LoadTask {
-
-    index: number;
-    asset: AssetReference;
-    tasks: LoadTask[];
-
-    constructor(index: number, asset: AssetReference, tasks: LoadTask[]) {
-        this.index = index;
-        this.asset = asset;
-        this.tasks = tasks;
-        tasks.push(this);
-        this.awaitLoading();
-    }
-
-    private async awaitLoading() {
-        if (this.asset && !this.asset.isLoaded()) {
-            if (debug)
-                console.log("Preload start: " + this.asset.uri, this.index);
-            await this.asset.preload();
-            if (debug)
-                console.log("Preload finished: " + this.asset.uri, this.index);
-        }
-
-        const i = this.tasks.indexOf(this);
-        if (i >= 0) this.tasks.splice(i, 1);
-    }
-}
+import { AssetReference } from "../engine/engine_addressables.js";
+import { InputEvents } from "../engine/engine_input.js";
+import { isLocalNetwork } from "../engine/engine_networking_utils.js";
+import { delay, getParam, setParamWithoutReload } from "../engine/engine_utils.js";
+import { serializable } from "../engine/engine_serialization.js";
+import { Behaviour, GameObject } from "./Component.js";
+import { registerObservableAttribute } from "../engine/engine_element_extras.js";
+import { Object3D } from "three";
+
+const debug = getParam("debugsceneswitcher");
+
+const ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME = "scene";
+registerObservableAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
+
+// ContextRegistry.registerCallback(ContextEvent.ContextRegistered, async _ => {
+//     // We need to defer import to not get issues with circular dependencies
+//     import("../engine/engine_element").then(res => {
+//         const webcomponent = res.NeedleEngineHTMLElement;
+//         if (debug) console.log("SceneSwitcher: registering scene attribute", webcomponent.observedAttributes);
+//         if (!webcomponent.observedAttributes.includes(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME))
+//             webcomponent.observedAttributes.push(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
+//     });
+// });
+
+const couldNotLoadScenePromise = Promise.resolve(false);
+
+export type LoadSceneEvent = {
+    switcher: SceneSwitcher;
+    scene: AssetReference;
+    index: number;
+}
+
+/** The ISceneEventListener is called by the SceneSwitcher when a scene is loaded or unloaded. It must be added to the root object of your scene */
+export interface ISceneEventListener {
+    /** Called when the scene is loaded and added */
+    sceneOpened?(): Promise<void>
+    /** Called before the scene is being removed (due to another scene being loaded) */
+    sceneClosing?(): Promise<void>
+}
+
+export class SceneSwitcher extends Behaviour {
+
+    @serializable(AssetReference)
+    scenes!: AssetReference[];
+
+    @serializable(AssetReference)
+    loadingScene!: AssetReference;
+
+    /** the url parameter that is set/used to store the currently loaded scene in, set to "" to disable */
+    @serializable()
+    queryParameterName: string = "scene";
+
+    /** 
+     * when enabled the scene name will be used as the query parameter (otherwise the scene index will be used)
+     * Needs `queryParameterName` set
+     * */
+    @serializable()
+    useSceneName: boolean = true;
+
+    @serializable()
+    clamp: boolean = true;
+
+    /** when enabled the new scene is pushed to the browser navigation history, only works with a valid query parameter set */
+    @serializable()
+    useHistory: boolean = true;
+
+    /** when enabled you can switch between scenes using keyboard left, right, A and D or number keys */
+    @serializable()
+    useKeyboard: boolean = true;
+
+    /** when enabled you can switch between scenes using swipe (mobile only) */
+    @serializable()
+    useSwipe: boolean = true;
+
+    /** when enabled will automatically apply the environment scene lights */
+    @serializable()
+    useSceneLighting: boolean = true;
+
+    /** how many scenes after the currently active scene should be preloaded */
+    @serializable()
+    preloadNext: number = 1;
+
+    /** how many scenes before the currently active scene should be preloaded */
+    @serializable()
+    preloadPrevious: number = 1;
+
+    /** how many scenes can be loaded in parallel */
+    @serializable()
+    preloadConcurrent: number = 2;
+
+
+    get currentIndex(): number { return this._currentIndex; }
+
+    private _currentIndex: number = -1;
+    private _currentScene: AssetReference | undefined = undefined;
+    private _engineElementOverserver: MutationObserver | undefined = undefined;
+
+    private _preloadScheduler?: PreLoadScheduler;
+
+    awake(): void {
+        if (debug) console.log("SceneSwitcher", this);
+    }
+
+    async start() {
+        if (this._currentIndex === -1 && !await this.tryLoadFromQueryParam()) {
+            const value = this.context.domElement.getAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
+            // let locked = this.lock;
+            try {
+                // this.lock = false;
+                if (value === null || !await this.trySelectSceneFromValue(value)) {
+                    if (this._currentIndex === -1)
+                        this.select(0);
+                }
+            }
+            finally {
+                // this.lock = locked;
+            }
+        }
+    }
+
+    onEnable(): void {
+        globalThis.addEventListener("popstate", this.onPopState);
+        this.context.input.addEventListener(InputEvents.KeyDown, this.onKeyDown);
+        this.context.input.addEventListener(InputEvents.PointerMove, this.onPointerMove);
+        this.context.input.addEventListener(InputEvents.PointerUp, this.onPointerUp);
+
+        if (!this._engineElementOverserver) {
+            this._engineElementOverserver = new MutationObserver((mutations) => {
+                for (const mut of mutations) {
+                    if (mut.type === "attributes" && mut.attributeName === ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME) {
+                        const value = this.context.domElement.getAttribute(ENGINE_ELEMENT_SCENE_ATTRIBUTE_NAME);
+                        if (value !== null) {
+                            this.trySelectSceneFromValue(value);
+                        }
+                    }
+                }
+            });
+        }
+
+        this._engineElementOverserver.observe(this.context.domElement, {
+            attributes: true
+        });
+
+        if (!this._preloadScheduler)
+            this._preloadScheduler = new PreLoadScheduler(this);
+        this._preloadScheduler.maxLoadAhead = this.preloadNext;
+        this._preloadScheduler.maxLoadBehind = this.preloadPrevious;
+        this._preloadScheduler.maxConcurrent = this.preloadConcurrent;
+        this._preloadScheduler.begin();
+
+        // Begin loading the loading scene
+        // if (this.loadingScene) this.loadingScene.loadAssetAsync();
+    }
+
+    onDisable(): void {
+        globalThis.removeEventListener("popstate", this.onPopState);
+        this.context.input.removeEventListener(InputEvents.KeyDown, this.onKeyDown);
+        this.context.input.removeEventListener(InputEvents.PointerMove, this.onPointerMove);
+        this.context.input.removeEventListener(InputEvents.PointerUp, this.onPointerUp);
+        this._preloadScheduler?.stop();
+    }
+
+    private onPopState = async (_state: PopStateEvent) => {
+        if (!this.useHistory) return;
+        const wasUsingHistory = this.useHistory;
+        try {
+            this.useHistory = false;
+            let didResolve = false;
+            if (this.queryParameterName)
+                didResolve = await this.tryLoadFromQueryParam();
+            if (!didResolve) {
+                const state = _state?.state;
+                if (state && state.startsWith(this.guid)) {
+                    const value = state.substr(this.guid.length + 2);
+                    if (debug) console.log("PopState", value);
+                    await this.trySelectSceneFromValue(value);
+                }
+            }
+        }
+        finally {
+            this.useHistory = wasUsingHistory;
+        }
+    }
+
+    private normalizedSwipeThresholdX = 0.1;
+    private _didSwipe: boolean = false;
+    private onPointerMove = (e: any) => {
+        if (!this.useSwipe) return;
+        if (!this._didSwipe && e.button === 0 && e.pointerType === "touch" && this.context.input.getPointerPressedCount() === 1) {
+            const delta = this.context.input.getPointerPositionDelta(e.button);
+            if (delta) {
+                const normalizedX = delta.x / this.context.domWidth;
+                if (normalizedX >= this.normalizedSwipeThresholdX) {
+                    this._didSwipe = true;
+                    this.selectPrev();
+                }
+                else if (normalizedX <= -this.normalizedSwipeThresholdX) {
+                    this._didSwipe = true;
+                    this.selectNext();
+                }
+            }
+        }
+    }
+
+    private onPointerUp = (e: any) => {
+        if (e.button === 0) {
+            this._didSwipe = false;
+        }
+    };
+
+    private onKeyDown = (e: any) => {
+        if (!this.useKeyboard) return;
+        if (!this.scenes) return;
+        const key = e.key.toLowerCase();
+        if (!key) return;
+        const index = parseInt(key) - 1;
+        if (index >= 0) {
+            this.trySelectSceneFromValue(index);
+            return;
+        }
+        switch (key) {
+            case "arrowright":
+            case "d":
+                this.selectNext();
+                break;
+            case "arrowleft":
+            case "a":
+                this.selectPrev();
+                break;
+        }
+    }
+
+    selectNext(): Promise<boolean> {
+        return this.select(this._currentIndex + 1);
+    }
+
+    selectPrev(): Promise<boolean> {
+        return this.select(this._currentIndex - 1);
+    }
+
+    select(index: number | string): Promise<boolean> {
+        if (debug) console.log("select", index);
+
+        if (typeof index === "object") {
+            // If a user tries to reference a scene object in a UnityEvent and invoke select(obj) 
+            // Then the object will be serialized as a object { guid : ... } or with the index json pointer
+            // This case is not supported right now. Object references in the editor must not be scene references
+            console.warn("Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
+        }
+
+        if (typeof index === "string") {
+            // If the parameter is a string we try to resolve the scene by its uri
+            // it's either already known in the scenes array
+            // or we create/get a new AssetReference and try to switch to that
+            const scene = this.scenes?.find(s => s.uri === index);
+            if (!scene) {
+                // Ok the scene is unknown to the scene switcher
+                // we create a new asset reference (or get an existing one)
+                // And switch to that. With this we can not modify the history
+                // Until the scene switcher can store the uri in the history instead of the index
+                const reference = AssetReference.getOrCreate(this.sourceId ?? "", index, this.context);
+                return this.switchScene(reference);
+            }
+            if (scene) index = this.scenes?.indexOf(scene);
+            else return couldNotLoadScenePromise;
+        }
+
+        if (!this.scenes?.length) return couldNotLoadScenePromise;
+        if (index < 0) {
+            if (this.clamp) return couldNotLoadScenePromise;
+            index = this.scenes.length - 1;
+        }
+        else if (index >= this.scenes.length) {
+            if (this.clamp) return couldNotLoadScenePromise;
+            index = 0;
+        }
+        const scene = this.scenes[index];
+        return this.switchScene(scene);
+    }
+
+
+    // this is the scene that was requested last
+    private __lastSwitchScene?: AssetReference;
+    private __lastSwitchScenePromise?: Promise<boolean>;
+
+    async switchScene(scene: AssetReference): Promise<boolean> {
+        if (!(scene instanceof AssetReference)) {
+            const type = typeof scene;
+            if (type === "string") {
+                return this.select(scene);
+            }
+            else if (type === "number") {
+                return this.select(scene);
+            }
+            else {
+                console.warn("SceneSwitcher: Can't switch to scene", scene, "of type", type);
+                return false;
+            }
+        }
+
+        // ensure that we never run the same scene switch multiple times (at the same time) for the same requested scene
+        if (this.__lastSwitchScene === scene && this.__lastSwitchScenePromise) {
+            return this.__lastSwitchScenePromise;
+        }
+        this.__lastSwitchScene = scene;
+        this.__lastSwitchScenePromise = this.__internalSwitchScene(scene);
+        const res = await this.__lastSwitchScenePromise;
+        return res;
+    }
+    async __internalSwitchScene(scene: AssetReference): Promise<boolean> {
+        if (this._currentScene) {
+            if (debug) console.log("UNLOAD", scene.uri)
+            const sceneListener = this.tryGetSceneEventListener(this._currentScene.asset as any as Object3D);
+            if (sceneListener?.sceneClosing) {
+                const res = sceneListener.sceneClosing();
+                if (res instanceof Promise) await res;
+            }
+            this._currentScene.unload();
+        }
+        this._currentScene = undefined;
+
+        const index = this._currentIndex = this.scenes?.indexOf(scene) ?? -1;
+        try {
+            const loadStartEvt = new CustomEvent<LoadSceneEvent>("loadscene-start", { detail: { scene: scene, switcher: this, index: index } })
+            this.dispatchEvent(loadStartEvt);
+            await this.onStartLoading();
+            await scene.loadAssetAsync().catch(console.error);
+            await this.onEndLoading();
+            const finishedEvt = new CustomEvent<LoadSceneEvent>("loadscene-finished", { detail: { scene: scene, switcher: this, index: index } });
+            this.dispatchEvent(finishedEvt);
+            if (finishedEvt.defaultPrevented) {
+                if (debug) console.warn("Adding loaded scene prevented:", scene, finishedEvt);
+                return false;
+            }
+            if (!scene.asset) {
+                if (debug) console.warn("Failed loading scene:", scene);
+                return false;
+            }
+            if (this._currentIndex === index) {
+                if (debug) console.log("ADD", scene.uri)
+                this._currentScene = scene;
+                GameObject.add(scene.asset, this.gameObject);
+                if (this.useSceneLighting)
+                    this.context.sceneLighting.enable(scene);
+                if (this.useHistory && index >= 0) {
+                    // take the index as the query parameter value
+                    let queryParameterValue = index.toString();
+                    // unless the user defines that he wants to use the scene name
+                    if (this.useSceneName) {
+                        queryParameterValue = sceneUriToName(scene.uri);
+                    }
+                    // save the loaded scene as an url parameter
+                    if (this.queryParameterName?.length)
+                        setParamWithoutReload(this.queryParameterName, queryParameterValue, this.useHistory);
+                    // or set the history state without updating the url parameter
+                    else {
+                        const lastState = history.state;
+                        const stateName = this.guid + "::" + index;
+                        if (lastState !== stateName)
+                            history.pushState(stateName, "unused", location.href);
+                    }
+                }
+                // Call SceneListener opened callback (if a SceneListener is in the scene)
+                const sceneListener = this.tryGetSceneEventListener(scene.asset as any as Object3D);
+                if (sceneListener?.sceneOpened) {
+                    const res = sceneListener.sceneOpened();
+                    if (res instanceof Promise) await res;
+                }
+                return true;
+            }
+        }
+        catch (err) {
+            console.error(err);
+        }
+        return false;
+    }
+
+    preload(index: number) {
+        if (index >= 0 && index < this.scenes.length) {
+            const scene = this.scenes[index];
+            if (scene instanceof AssetReference)
+                return scene.preload();
+        }
+        return couldNotLoadScenePromise;
+    }
+
+    private tryLoadFromQueryParam() {
+        if (!this.queryParameterName?.length) return couldNotLoadScenePromise;
+        // try restore the scene from the url
+        const value = getParam(this.queryParameterName);
+        if (typeof value === "boolean") return couldNotLoadScenePromise;
+        return this.trySelectSceneFromValue(value);
+    }
+
+    /** try to select a scene from a string or index */
+    private trySelectSceneFromValue(value: string | number) {
+
+        if (typeof value === "string") {
+            const index = parseInt(value as string);
+            if (index >= 0 && index < this.scenes.length) {
+                return this.select(index);;
+            }
+            else {
+                // Try to find a scene with a matching name
+                // we don't care about casing. e.g. Scene1 and scene1 should both match
+                const lowerCaseValue = value.toLowerCase();
+                for (let i = 0; i < this.scenes.length; i++) {
+                    const scene = this.scenes[i];
+                    if (!scene) continue;
+                    if (sceneUriToName(scene.uri).toLowerCase().includes(lowerCaseValue)) {
+                        return this.select(i);;
+                    }
+                }
+            }
+        }
+        else if (typeof value === "number") {
+            if (value >= 0 && value < this.scenes.length) {
+                return this.select(value);;
+            }
+        }
+
+        if (isLocalNetwork()) console.warn("Can not find scene: \"" + value + "\"", this)
+
+        return couldNotLoadScenePromise;
+    }
+
+    private _lastLoadingScene: AssetReference | undefined = undefined;
+    private _loadingScenePromise: Promise<boolean> | undefined = undefined;
+    private _isCurrentlyLoading: boolean = false;
+    private async onStartLoading() {
+        this._isCurrentlyLoading = true;
+        if (this.loadingScene) {
+            // save the last loading scene reference so that it can be changed at runtime
+            // since we cache the loading promise here
+            if(this._lastLoadingScene !== this.loadingScene) {
+                this._loadingScenePromise = undefined;
+            }
+            this._lastLoadingScene = this.loadingScene;
+            if (!this._loadingScenePromise) {
+                this._loadingScenePromise = this.loadingScene?.loadAssetAsync();
+            }
+            await this._loadingScenePromise;
+            if (this._isCurrentlyLoading && this.loadingScene?.asset) {
+                if (debug) console.log("Add loading scene", this.loadingScene.uri, this.loadingScene.asset)
+                const obj = this.loadingScene.asset as any as Object3D;
+                GameObject.add(obj, this.gameObject);
+                const sceneListener = this.tryGetSceneEventListener(obj);
+                if (sceneListener?.sceneOpened) {
+                    const res = sceneListener.sceneOpened();
+                    if (res instanceof Promise) await res;
+                }
+            }
+        }
+    }
+    private async onEndLoading() {
+        this._isCurrentlyLoading = false;
+        if (this.loadingScene?.asset) {
+            if (debug) console.log("Remove loading scene", this.loadingScene.uri);
+            const obj = this.loadingScene.asset as any as Object3D;
+            // try to find an ISceneEventListener component
+            const sceneListener = this.tryGetSceneEventListener(obj);
+            if (typeof sceneListener?.sceneClosing === "function") {
+                const res = sceneListener.sceneClosing();
+                if (res instanceof Promise) await res;
+            }
+            GameObject.remove(obj);
+        }
+    }
+
+    private tryGetSceneEventListener(obj: Object3D, level: number = 0): ISceneEventListener | null {
+        const sceneListener = GameObject.foreachComponent(obj, c => (c as any as ISceneEventListener).sceneClosing ? c : undefined) as ISceneEventListener | undefined;
+        // if we didnt find any component with the listener on the root object
+        // we also check the first level of its children because a scene might be a group
+        if (level === 0 && !sceneListener && obj.children.length) {
+            for (const ch of obj.children) {
+                const res = this.tryGetSceneEventListener(ch, level + 1);
+                if (res) return res;
+            }
+        }
+        if (!sceneListener) return null;
+        return sceneListener;
+    }
+}
+
+
+function sceneUriToName(uri: string): string {
+    const name = uri.split("/").pop();
+    const value = name?.split(".").shift();
+    if (value?.length) return value;
+    return uri;
+}
+
+
+
+class PreLoadScheduler {
+    maxLoadAhead: number;
+    maxLoadBehind: number;
+    maxConcurrent: number;
+
+    private _isRunning: boolean = false;
+    private _switcher: SceneSwitcher;
+    private _loadTasks: LoadTask[] = [];
+    private _maxConcurrentLoads: number = 1;
+
+    constructor(rooms: SceneSwitcher, ahead: number = 1, behind: number = 1, maxConcurrent: number = 2) {
+        this._switcher = rooms;
+        this.maxLoadAhead = ahead;
+        this.maxLoadBehind = behind;
+        this.maxConcurrent = maxConcurrent;
+    }
+
+    begin() {
+        if (this._isRunning) return;
+        if (debug) console.log("Preload begin")
+        this._isRunning = true;
+        let lastRoom: number = -1;
+        let searchDistance: number;
+        let searchCall: number;
+        const array = this._switcher.scenes;
+        const interval = setInterval(() => {
+            if (this.allLoaded()) {
+                if (debug)
+                    console.log("All scenes loaded");
+                this.stop();
+            }
+            if (!this._isRunning) {
+                clearInterval(interval);
+                return;
+            }
+            if (this.canLoadNewScene() === false) return;
+            if (lastRoom !== this._switcher.currentIndex) {
+                lastRoom = this._switcher.currentIndex;
+                searchCall = 0;
+                searchDistance = 0;
+            }
+            const searchForward = searchCall % 2 === 0;
+            if (searchForward) searchDistance += 1;
+            searchCall += 1;
+            const maxSearchDistance = searchForward ? this.maxLoadAhead : this.maxLoadBehind;
+            if (searchDistance > maxSearchDistance) return;
+            const roomIndex = searchForward ? lastRoom + searchDistance : lastRoom - searchDistance;
+            if (roomIndex < 0) return;
+            // if (roomIndex < 0) roomIndex = array.length + roomIndex;
+            if (roomIndex < 0 || roomIndex >= array.length) return;
+            const scene = array[roomIndex];
+            new LoadTask(roomIndex, scene, this._loadTasks);
+        }, 200);
+    }
+
+    stop() {
+        this._isRunning = false;
+    }
+
+    canLoadNewScene(): boolean {
+        return this._loadTasks.length < this._maxConcurrentLoads;
+    }
+
+    allLoaded(): boolean {
+        if (this._switcher.scenes) {
+            for (const scene of this._switcher.scenes) {
+                if (scene?.isLoaded() === false) return false;
+            }
+        }
+        return true;
+    }
+}
+
+class LoadTask {
+
+    index: number;
+    asset: AssetReference;
+    tasks: LoadTask[];
+
+    constructor(index: number, asset: AssetReference, tasks: LoadTask[]) {
+        this.index = index;
+        this.asset = asset;
+        this.tasks = tasks;
+        tasks.push(this);
+        this.awaitLoading();
+    }
+
+    private async awaitLoading() {
+        if (this.asset && !this.asset.isLoaded()) {
+            if (debug)
+                console.log("Preload start: " + this.asset.uri, this.index);
+            await this.asset.preload();
+            if (debug)
+                console.log("Preload finished: " + this.asset.uri, this.index);
+        }
+
+        const i = this.tasks.indexOf(this);
+        if (i >= 0) this.tasks.splice(i, 1);
+    }
+}