@needle-tools/engine 3.36.3-beta.1 → 3.36.4-beta

package/src/engine/engine_addressables.ts

@@ -45,11 +45,17 @@ export class Addressables {
     }
 
 
-    findAssetReference(key: string): AssetReference | null {
-        return this._assetReferences[key] || null;
+    /**
+     * Find a registered AssetReference by its URL
+     */
+    findAssetReference(url: string): AssetReference | null {
+        return this._assetReferences[url] || null;
     }
 
-    /** @internal */
+    /** 
+     * Register an asset reference
+     * @internal
+     */
     registerAssetReference(ref: AssetReference): AssetReference {
         if (!ref.uri) return ref;
         if (!this._assetReferences[ref.uri]) {
@@ -83,8 +89,32 @@ const $assetReference = Symbol("assetReference");
  */
 export class AssetReference {
 
+    /**
+     * Experimental!  
+     * @internal
+     * Get an AssetReference for a URL to be easily loaded.  
+     * AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.
+     * @param url The URL of the asset to load. The url can be relative or absolute.
+     * @param context The context to use for loading the asset  
+     * @returns the AssetReference for the URL
+     */
+    static getOrCreateFromUrl(url: string, context?: Context): AssetReference {
+        if (!context) {
+            context = Context.Current;
+            if (!context)
+                throw new Error("Context is required when sourceId is a string. When you call this method from a component you can call it with \"getOrCreate(this, url)\" where \"this\" is the component.");
+        }
+        const addressables = context.addressables;
+        const existing = addressables.findAssetReference(url);
+        if (existing) return existing;
+        const ref = new AssetReference(url, context.hash);
+        addressables.registerAssetReference(ref);
+        return ref;
+    }
+
     /** 
-     * Get an AssetReference for a URL to be easily loaded. AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.
+     * Get an AssetReference for a URL to be easily loaded.   
+     * AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.
      */
     static getOrCreate(sourceId: SourceIdentifier | IComponent, url: string, context?: Context): AssetReference {
 
@@ -515,6 +545,7 @@ export class ImageReference {
 }
 
 
+/** @internal */
 export class ImageReferenceSerializer extends TypeSerializer {
     constructor() {
         super([ImageReference], "ImageReferenceSerializer");
@@ -578,6 +609,7 @@ export class FileReference {
 }
 
 
+/** @internal */
 export class FileReferenceSerializer extends TypeSerializer {
     constructor() {
         super([FileReference], "FileReferenceSerializer");

package/src/engine/engine_input.ts

@@ -1,4 +1,4 @@
-import { Intersection,Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
+import { Intersection, Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
 
 import { showBalloonMessage, showBalloonWarning } from './debug/debug.js';
 import { Context } from './engine_setup.js';
@@ -207,6 +207,9 @@ declare type EventListenerOptions = {
     signal?: AbortSignal;
 }
 
+/**
+ * The input system is responsible for handling all input events like pointer events (mouse, touch, xr controllers) and keyboard events.
+ */
 export class Input implements IInput {
 
     /** This is a list of event listeners per event type (e.g. pointerdown, pointerup, keydown...). Each entry contains a priority and list of listeners.  
@@ -649,6 +652,7 @@ export class Input implements IInput {
         vec2.y = -((vec2.y - this.context.domY) / this.context.domHeight) * 2 + 1;
     }
 
+    /** @internal */
     constructor(context: Context) {
         this.context = context;
         this.context.post_render_callbacks.push(this.onEndOfFrame);

package/src/engine/engine_instancing.ts

@@ -6,6 +6,9 @@ export const $isUsingInstancing = Symbol("isUsingInstancing");
 export const $instancingRenderer = Symbol("instancingRenderer");
 export const $instancingAutoUpdateBounds = Symbol("instancingAutoUpdateBounds");
 
+/**
+ * Utility class for accessing instancing related properties
+ */
 export class InstancingUtil {
 
     /** Is this object rendered using a InstancedMesh */

package/src/engine/engine_license.ts

@@ -10,6 +10,7 @@ const debug = getParam("debuglicense");
 let NEEDLE_ENGINE_LICENSE_TYPE: string = "basic";
 if (debug) console.log("License Type: " + NEEDLE_ENGINE_LICENSE_TYPE)
 
+/** @internal */
 export function hasProLicense() {
     switch (NEEDLE_ENGINE_LICENSE_TYPE) {
         case "pro":
@@ -19,6 +20,7 @@ export function hasProLicense() {
     return false;
 }
 
+/** @internal */
 export function hasIndieLicense() {
     switch (NEEDLE_ENGINE_LICENSE_TYPE) {
         case "indie":
@@ -27,11 +29,13 @@ export function hasIndieLicense() {
     return false;
 }
 
+/** @internal */
 export function hasCommercialLicense() {
     return hasProLicense() || hasIndieLicense();
 }
 
 const _licenseCheckResultChangedCallbacks: ((result: boolean) => void)[] = [];
+/** @internal */
 export function onLicenseCheckResultChanged(cb: (result: boolean) => void) {
     if (hasProLicense() || hasIndieLicense())
         return cb(true);

package/src/engine/engine_networking_instantiate.ts

@@ -151,6 +151,8 @@ export function beginListenDestroy(context: Context) {
 
 // when a file is instantiated via some server (e.g. via file drop) we also want to send the info where the file can be downloaded
 // doing it this route will ensure we have 
+
+/** @internal */
 export class HostData {
     filename: string;
     hash: string;

package/src/engine/engine_scenetools.ts

@@ -15,6 +15,7 @@ import { registerComponentExtension, registerExtensions } from "./extensions/ext
 import { NEEDLE_components } from "./extensions/NEEDLE_components.js";
 
 
+/** @internal */
 export class NeedleGltfLoader implements INeedleGltfLoader {
     createBuiltinComponents(context: Context, gltfId: string, gltf: any, seed: number | UIDProvider | null, extension?: NEEDLE_components | undefined) {
         return createBuiltinComponents(context, gltfId, gltf, seed, extension);
@@ -103,6 +104,13 @@ export async function createGLTFLoader(url: string, context: Context) {
     return loader;
 }
 
+/** Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.   
+ * @param context The current context
+ * @param data The gltf data as string or ArrayBuffer
+ * @param path The path to the gltf file
+ * @param seed The seed for generating unique ids
+ * @returns The loaded gltf object
+ */
 export async function parseSync(context: Context, data: string | ArrayBuffer, path: string, seed: number | UIDProvider | null): Promise<GLTF | undefined> {
     if (typeof path !== "string") {
         console.warn("Parse gltf binary without path, this might lead to errors in resolving extensions. Please provide the source path of the gltf/glb file", path, typeof path);
@@ -153,6 +161,15 @@ export async function parseSync(context: Context, data: string | ArrayBuffer, pa
     });
 }
 
+/**
+ * Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.  
+ * @param context The current context
+ * @param url The url to the gltf file
+ * @param sourceId The source id of the gltf file - this is usually the url
+ * @param seed The seed for generating unique ids
+ * @param prog A progress callback
+ * @returns The loaded gltf object
+ */
 export async function loadSync(context: Context, url: string, sourceId: string, seed: number | UIDProvider | null, prog?: (ProgressEvent) => void): Promise<GLTF | undefined> {
     // better to create new loaders every time
     // (maybe we can cache them...)

package/src/engine/engine_shaders.ts

@@ -11,6 +11,12 @@ const white = new Uint8Array(4);
 white[0] = 255; white[1] = 255; white[2] = 255; white[3] = 255;
 export const whiteDefaultTexture = new DataTexture(white, 1, 1, RGBAFormat);
 
+/**
+ * Creates a new texture with a single color
+ * @param col Color to use
+ * @param size Size of the texture
+ * @returns A texture with the specified color
+ */
 export function createFlatTexture(col: RGBAColor | Color, size: number = 1) {
     const hasAlpha = "alpha" in col;
     const length = size * size;
@@ -31,6 +37,15 @@ export function createFlatTexture(col: RGBAColor | Color, size: number = 1) {
     return tex;
 }
 
+/**
+ * Creates a new texture with three colors
+ * @param col0 First color
+ * @param col1 Second color
+ * @param col2 Third color
+ * @param width Width of the texture
+ * @param height Height of the texture
+ * @returns A texture with the specified colors
+ */
 export function createTrilightTexture<T extends Color>(col0: T, col1: T, col2: T, width: number = 1, height: number = 3) {
     const hasAlpha = false;// "alpha" in col0;
     const channels = 4;
@@ -62,11 +77,13 @@ export function createTrilightTexture<T extends Color>(col0: T, col1: T, col2: T
     return tex;
 }
 
+/** @internal */
 export enum Stage {
     Vertex,
     Fragment,
 }
 
+/** @internal */
 export class UnityShaderStage {
     stage: Stage;
     code: string;
@@ -105,9 +122,11 @@ class ShaderLib {
     }
 }
 
+/** @internal */
 export const lib = new ShaderLib();
 
 
+/** @internal */
 export function ToUnityMatrixArray(mat: Matrix4, buffer?: Array<Vector4>): Array<Vector4> {
     const arr = mat.elements;
     if (!buffer)
@@ -126,6 +145,8 @@ export function ToUnityMatrixArray(mat: Matrix4, buffer?: Array<Vector4>): Array
 
 const noAmbientLight: Array<number> = [];
 const copyBuffer: Array<number> = [];
+
+/** @internal */
 export function SetUnitySphericalHarmonics(obj: object, array?: number[]) {
 
     if (noAmbientLight.length === 0) {
@@ -147,6 +168,7 @@ export function SetUnitySphericalHarmonics(obj: object, array?: number[]) {
     obj["unity_SHC"] = { value: new Vector4(array[24], array[25], array[26], 1) };
 }
 
+/** @internal */
 export class ShaderBundle {
     readonly vertexShader: string;
     readonly fragmentShader: string;
@@ -159,6 +181,7 @@ export class ShaderBundle {
     }
 }
 
+/** @internal */
 export async function FindShaderTechniques(shaderData: SHADERDATA.ShaderData, id: number): Promise<ShaderBundle | null> {
     // console.log(shaderData);
     if (!shaderData) {
@@ -191,6 +214,7 @@ export async function FindShaderTechniques(shaderData: SHADERDATA.ShaderData, id
     return null;
 }
 
+/** @internal */
 async function loadShaderCode(shader: SHADERDATA.Shader) {
     const uri = shader.uri;
     if (!uri) return;

package/src/engine/engine_texture.ts

@@ -21,6 +21,9 @@ const _prevVisible = Symbol("previous-visibility");
  */
 export class RenderTexture extends WebGLRenderTarget {
 
+    /**
+     * Render the scene to the texture
+     */
     render(scene: Object3D, camera: Camera, renderer: WebGLRenderer | EffectComposer) {
         if (renderer instanceof EffectComposer) {
             if (!this["_unsupported_effectcomposer_warning"]) {

package/src/engine/engine_three_utils.ts

@@ -1,5 +1,5 @@
-import { AnimationAction, Euler, Mesh,Object3D, PerspectiveCamera, PlaneGeometry, Quaternion, Scene, Texture, Uniform, Vector3 } from "three";
-import { ShaderMaterial,WebGLRenderer } from "three";
+import { AnimationAction, Euler, Mesh, Object3D, PerspectiveCamera, PlaneGeometry, Quaternion, Scene, Texture, Uniform, Vector3 } from "three";
+import { ShaderMaterial, WebGLRenderer } from "three";
 
 import { Mathf } from "./engine_math.js"
 import { CircularBuffer } from "./engine_utils.js";
@@ -13,6 +13,7 @@ export function slerp(vec: Vector3, end: Vector3, t: number) {
 }
 
 const flipYQuat: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
+
 export function lookAtInverse(obj: Object3D, target: Vector3) {
 
     obj.lookAt(target);
@@ -50,6 +51,14 @@ export function lookAtObject(object: Object3D, target: Object3D, keepUpDirection
 
 
 const _tempVecs = new CircularBuffer(() => new Vector3(), 100);
+
+/** Gets a temporary vector. If a vector is passed in it will be copied to the temporary vector    
+ * Temporary vectors are cached and reused internally. Don't store them!  
+ * @param vecOrX the vector to copy or the x value
+ * @param y the y value
+ * @param z the z value
+ * @returns a temporary vector
+ */
 export function getTempVector(vecOrX?: Vector3 | number | DOMPointReadOnly, y?: number, z?: number) {
     const vec = _tempVecs.get();
     if (vecOrX instanceof Vector3) vec.copy(vecOrX);
@@ -62,6 +71,13 @@ export function getTempVector(vecOrX?: Vector3 | number | DOMPointReadOnly, y?:
     return vec;
 }
 const _tempQuats = new CircularBuffer(() => new Quaternion(), 100);
+
+/**
+ * Gets a temporary quaternion. If a quaternion is passed in it will be copied to the temporary quaternion  
+ * Temporary quaternions are cached and reused internally. Don't store them!
+ * @param value the quaternion to copy
+ * @returns a temporary quaternion
+ */
 export function getTempQuaternion(value?: Quaternion | DOMPointReadOnly) {
     const val = _tempQuats.get();
     if (value instanceof Quaternion) val.copy(value);
@@ -73,6 +89,13 @@ export function getTempQuaternion(value?: Quaternion | DOMPointReadOnly) {
 const _worldPositions = new CircularBuffer(() => new Vector3(), 100);
 const _lastMatrixWorldUpdateKey = Symbol("lastMatrixWorldUpdateKey");
 
+/**
+ * Get the world position of an object
+ * @param obj the object to get the world position from
+ * @param vec a vector to store the result in. If not passed in a temporary vector will be used
+ * @param updateParents if true the parents will be updated before getting the world position
+ * @returns the world position
+ */
 export function getWorldPosition(obj: Object3D, vec: Vector3 | null = null, updateParents: boolean = true): Vector3 {
     const wp = vec ?? _worldPositions.get();
     if (!obj) return wp.set(0, 0, 0);
@@ -87,20 +110,34 @@ export function getWorldPosition(obj: Object3D, vec: Vector3 | null = null, upda
     return wp;
 }
 
-export function setWorldPosition(obj: Object3D, val: Vector3) {
-    if (!obj) return;
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param val the world position to set
+ */
+export function setWorldPosition(obj: Object3D, val: Vector3): Object3D {
+    if (!obj) return obj;
     const wp = _worldPositions.get();
     if (val !== wp)
         wp.copy(val);
     const obj2 = obj?.parent ?? obj;
     obj2.worldToLocal(wp);
     obj.position.set(wp.x, wp.y, wp.z);
+    return obj;
 }
 
-export function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number) {
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param x the x position
+ * @param y the y position
+ * @param z the z position
+ */
+export function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number): Object3D {
     const wp = _worldPositions.get();
     wp.set(x, y, z);
     setWorldPosition(obj, wp);
+    return obj;
 }
 
 
@@ -254,7 +291,7 @@ export function logHierarchy(root: Object3D | null | undefined, collapsible: boo
 
 export function getParentHierarchyPath(obj: Object3D): string {
     let path = obj?.name || "";
-    if(!obj) return path;
+    if (!obj) return path;
     let parent = obj.parent;
     while (parent) {
         path = parent.name + "/" + path;
@@ -278,6 +315,9 @@ export function isAnimationAction(obj: object) {
 
 
 
+/**
+ * Utility class to perform various graphics operations like copying textures to canvas
+ */
 export class Graphics {
     private static planeGeometry = new PlaneGeometry(2, 2, 1, 1);
     private static renderer: WebGLRenderer | undefined = undefined;
@@ -300,6 +340,9 @@ export class Graphics {
     }`;
     private static blipMaterial: ShaderMaterial | undefined = undefined;
 
+    /**
+     * Create a blit material for copying textures
+     */
     static createBlitMaterial(fragment: string): ShaderMaterial {
         return new ShaderMaterial({
             uniforms: { map: new Uniform(null) },
@@ -309,7 +352,13 @@ export class Graphics {
     }
     private static mesh: Mesh | undefined = undefined;
 
-    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial) {
+    /** 
+     * Copy a texture to a new texture
+     * @param texture the texture to copy
+     * @param blitMaterial the material to use for copying (optional)
+     * @returns the newly created, copied texture
+    */
+    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial): Texture {
         const material = blitMaterial ?? this.blipMaterial!;
         material.uniforms.map.value = texture;
         material.needsUpdate = true;

package/src/engine/engine_types.ts

@@ -320,6 +320,9 @@ export type Vec4 = {
 
 const contactsVectorBuffer = new CircularBuffer(() => new Vector3(), 20);
 
+/**
+ * Holds information about physics contacts 
+ */
 export class ContactPoint {
 
     private readonly _point: Vec3;
@@ -350,6 +353,7 @@ export class ContactPoint {
         return target.set(this._tangentVelocity.x, this._tangentVelocity.y, this._tangentVelocity.z);
     }
 
+    /** @internal */
     constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number, tangentVelocity: Vec3) {
         this._point = point;
         this.distance = dist;
@@ -360,12 +364,15 @@ export class ContactPoint {
     }
 }
 
-/// all info in here must be readonly because the object is only created once per started collision
+/**
+ * Holds information about a collision event. Includes a list of contact points and the colliders involved
+ */
 export class Collision {
 
     /** The contact points of this collision. Contains information about positions, normals, distance, friction, impulse... */
     readonly contacts: ContactPoint[];
 
+    /** @internal */
     constructor(obj: IGameObject, otherCollider: ICollider, contacts: ContactPoint[]) {
         this.me = obj;
         this._collider = otherCollider;

package/src/engine/engine_util_decorator.ts

@@ -96,8 +96,9 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
 
 
 
-/** experimental attribute - use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).
- * Return false to prevent the original method from running.
+/** Experimental attribute  
+ * Use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).  
+ * Return false to prevent the original method from running.  
  */
 export const prefix = function <T>(type: Constructor<T>) {
     return function (target: IComponent | any, _propertyKey: string | { name: string }, _PropertyDescriptor: PropertyDescriptor) {

package/src/engine/engine_utils.ts

@@ -319,10 +319,12 @@ export function resolveUrl(source: SourceIdentifier | undefined, uri: string): s
     if (pathIndex >= 0) {
         // Take the source uri as the base path
         const basePath = source.substring(0, pathIndex + 1);
+        // make sure we don't have double slashes
+        while (basePath.endsWith("/") && uri.startsWith("/")) uri = uri.substring(1);
         // Append the relative uri
         const newUri = basePath + uri;
         // newUri = new URL(newUri, globalThis.location.href).href;
-        if (debugGetPath) console.log("source:", source, "- changed uri \nfrom", uri, "\n→ ", newUri, "\n" + basePath);
+        if (debugGetPath) console.log("source:", source, "changed uri \nfrom", uri, "\nto ", newUri, "\nbasePath: " + basePath);
         return newUri;
     }
     return uri;

package/src/engine-components/OrbitControls.ts

@@ -639,10 +639,17 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 expandByObjectRecursive(child);
             }
         }
+        let hasAnyObject = false;
         for (const object of objects) {
+            if (!object) continue;
+            hasAnyObject = true;
             object.updateMatrixWorld();
             expandByObjectRecursive(object);
         }
+        if (!hasAnyObject) {
+            console.warn("No objects to fit camera to...");
+            return;
+        }
 
         camera.updateMatrixWorld();
         camera.updateProjectionMatrix();

package/src/engine-components/SceneSwitcher.ts

@@ -1,6 +1,6 @@
 import { Object3D } from "three";
 
-import { AssetReference } from "../engine/engine_addressables.js";
+import { Addressables, AssetReference } from "../engine/engine_addressables.js";
 import { registerObservableAttribute } from "../engine/engine_element_extras.js";
 import { InputEvents } from "../engine/engine_input.js";
 import { isLocalNetwork } from "../engine/engine_networking_utils.js";
@@ -64,6 +64,7 @@ export interface ISceneEventListener {
  * - `loadscene-start`: Called when a scene starts loading
  * - `loadscene-finished`: Called when a scene finished loading
  * - `progress`: Called when a scene is loading and the progress changes
+ * - `scene-opened`: Called when a scene is loaded and added to the SceneSwitcher's GameObject
  * @example
  * ```ts
  * sceneSwitcher.addEventListener("loadscene-start", (e) => {
@@ -75,6 +76,9 @@ export interface ISceneEventListener {
  * sceneSwitcher.addEventListener("progress", (e) => {
  *  console.log("Loading progress", e.loaded, e.total);
  * });
+ * sceneSwitcher.addEventListener("scene-opened", (e) => {
+ * console.log("Scene opened", e.detail.scene.uri);
+ * });
  * ```
  * 
  */
@@ -159,10 +163,14 @@ export class SceneSwitcher extends Behaviour {
 
     private _preloadScheduler?: PreLoadScheduler;
 
+    /** @internal */
     awake(): void {
+        if (this.scenes === undefined) this.scenes = [];
+        
         if (debug) console.log("SceneSwitcher", this);
     }
 
+    /** @internal */
     async onEnable() {
         globalThis.addEventListener("popstate", this.onPopState);
         this.context.input.addEventListener(InputEvents.KeyDown, this.onInputKeyDown);
@@ -210,6 +218,7 @@ export class SceneSwitcher extends Behaviour {
         }
     }
 
+    /** @internal */
     onDisable(): void {
         globalThis.removeEventListener("popstate", this.onPopState);
         this.context.input.removeEventListener(InputEvents.KeyDown, this.onInputKeyDown);
@@ -288,14 +297,58 @@ export class SceneSwitcher extends Behaviour {
         }
     }
 
+    /**
+     * Add a scene to the SceneSwitcher.     
+     * If the scene is already added it will be added again.
+     * @param urlOrAssetReference The url of the scene or an AssetReference to the scene  
+     * @returns The AssetReference of the scene that was added
+     * @example
+     * ```ts
+     * // adding a scene:
+     * sceneSwitcher.addScene("scene1.glb");
+     * // add another scene and load it:
+     * const scene2 = sceneSwitcher.addScene("scene2.glb");
+     * sceneSwitcher.switchScene(scene2).then(res => { console.log("Scene loaded", res); });
+     * ```
+     */
+    addScene(urlOrAssetReference: string | AssetReference): AssetReference {
+        if (typeof urlOrAssetReference === "string") {
+            let assetReference = this.context.addressables.findAssetReference(urlOrAssetReference);
+            if (!assetReference) {
+                assetReference = new AssetReference(urlOrAssetReference);
+                this.context.addressables.registerAssetReference(assetReference);
+            }
+            this.scenes.push(assetReference);
+            return assetReference;
+        }
+
+        this.scenes.push(urlOrAssetReference);
+        return urlOrAssetReference;
+    }
+
+    /**
+     * Load the next scene in the scenes array ({@link this.currentIndex} + 1)  
+     * If the current scene is the last scene in the array and {@link this.clamp} is disabled then the first scene will be loaded.
+     * @returns a promise that resolves to true if the scene was loaded successfully    
+     */
     selectNext(): Promise<boolean> {
         return this.select(this._currentIndex + 1);
     }
 
+    /**
+     * Load the previous scene in the scenes array ({@link this.currentIndex} - 1)  
+     * If the current scene is the first scene in the array and {@link this.clamp} is disabled then the last scene will be loaded.
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     selectPrev(): Promise<boolean> {
         return this.select(this._currentIndex - 1);
     }
 
+    /**
+     * Load a scene by its index in the scenes array.
+     * @param index The index of the scene or a string that represents the scene uri (if the url is not known to the SceneSwitcher it will try to load the scene by its uri but it won't be added to the current scenes array. Use {@link addScene} to add a scene to the SceneSwitcher)  
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     select(index: number | string): Promise<boolean> {
         if (debug) console.log("select", index);
 
@@ -341,6 +394,19 @@ export class SceneSwitcher extends Behaviour {
     private __lastSwitchScene?: AssetReference;
     private __lastSwitchScenePromise?: Promise<boolean>;
 
+    /**
+     * Switch to a scene by its AssetReference.  
+     * If the scene is already loaded it will be unloaded and the new scene will be loaded.  
+     * If the scene is already loading it will wait for the scene to be loaded.  
+     * If the scene is already loaded and the same scene is requested again it will return the same promise that was returned the first time the scene was requested.  
+     * @param scene The AssetReference of the scene to switch to
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     * @example
+     * ```ts
+     * const myAssetReference = new AssetReference("scene1.glb");
+     * sceneSwitcher.switchScene(myAssetReference).then(res => { console.log("Scene loaded", res); });
+     * ```
+     */
     async switchScene(scene: AssetReference): Promise<boolean> {
         if (!(scene instanceof AssetReference)) {
             const type = typeof scene;
@@ -444,6 +510,9 @@ export class SceneSwitcher extends Behaviour {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
+
+                const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
+                this.dispatchEvent(openedEvt);
                 return true;
             }
         }