@needle-tools/engine 4.11.5-beta → 4.11.5-next.4201116

package/src/engine/engine_scenelighting.ts

@@ -1,4 +1,4 @@
-import { EquirectangularReflectionMapping, LightProbe, SphericalHarmonics3, SRGBColorSpace,Texture, Vector4, WebGLCubeRenderTarget } from "three";
+import { EquirectangularReflectionMapping, LightProbe, Source, SphericalHarmonics3, SRGBColorSpace, Texture, Vector4, WebGLCubeRenderTarget } from "three";
 
 import { AssetReference } from "./engine_addressables.js";
 import { Context } from "./engine_setup.js";
@@ -44,9 +44,16 @@ export class RendererData {
         this.context.pre_update_callbacks.push(this.preUpdate.bind(this))
     }
 
+    /**
+     * The id of the currently active scene light settings (source identifier).
+     */
     private _currentLightSettingsId?: SourceIdentifier;
     private _sceneLightSettings?: Map<SourceIdentifier, SceneLightSettings>;
 
+    get currentLightSettingsId(): SourceIdentifier | undefined {
+        return this._currentLightSettingsId;
+    }
+
     private preUpdate() {
         const time = this.context.time;
         this._timevec4.x = time.time;
@@ -82,11 +89,11 @@ export class RendererData {
 
     /** set the scene lighting from a specific scene. Will disable any previously enabled lighting settings */
     enable(sourceId: SourceIdentifier | AssetReference) {
-        if(sourceId instanceof AssetReference)
+        if (sourceId instanceof AssetReference)
             sourceId = sourceId.url;
         const settings = this._sceneLightSettings?.get(sourceId);
         if (!settings) {
-            if(debug) console.warn("No light settings found for", sourceId);
+            if (debug) console.warn("No light settings found for", sourceId);
             return false;
         }
         if (debug) console.log("Enable scene light settings", sourceId, settings);
@@ -100,7 +107,7 @@ export class RendererData {
 
     /** disable the lighting of a specific scene, will only have any effect if it is currently active */
     disable(sourceId: SourceIdentifier | AssetReference) {
-        if(sourceId instanceof AssetReference)
+        if (sourceId instanceof AssetReference)
             sourceId = sourceId.url;
         if (sourceId === null || sourceId === undefined) return false;
         const settings = this._sceneLightSettings?.get(sourceId);
@@ -112,8 +119,22 @@ export class RendererData {
         return true;
     }
 
-    /** Disables the currently active scene lighting (if any), returns the id of the previously active lighting */
-    disableCurrent() : SourceIdentifier | null {
+    /**
+     * Enables the currently active scene lighting (if any), returns the id of the enabled lighting.
+     * @returns The id of the enabled lighting, or null if no lighting is currently active.
+     */
+    enableCurrent(): SourceIdentifier | null {
+        if (this._currentLightSettingsId) {
+            this.enable(this._currentLightSettingsId);
+            return this._currentLightSettingsId ?? null;
+        }
+        return null;
+    }
+
+    /** Disables the currently active scene lighting (if any), returns the id of the previously active lighting
+     * @returns The id of the previously active lighting, or null if no lighting was active.
+     */
+    disableCurrent(): SourceIdentifier | null {
         if (this._currentLightSettingsId) {
             const prev = this._currentLightSettingsId;
             this.disable(this._currentLightSettingsId);
@@ -162,7 +183,7 @@ export class RendererData {
     private __currentReflectionId: SourceIdentifier | null = null;
 
     /** @internal */
-    internalEnableReflection(sourceId: SourceIdentifier) : Texture | null {
+    internalEnableReflection(sourceId: SourceIdentifier): Texture | null {
         this.__currentReflectionId = sourceId;
         const settings = this._sceneLightSettings?.get(sourceId);
 
@@ -181,6 +202,7 @@ export class RendererData {
                     const tex = existing.Source;
                     tex.mapping = EquirectangularReflectionMapping;
                     scene.environment = tex;
+                    scene.environmentIntensity = this.environmentIntensity || 1;
                     return tex;
                 }
                 else if (debug) console.warn("Could not find reflection for source", sourceId);
@@ -216,7 +238,7 @@ export class RendererData {
     /** @internal */
     internalDisableReflection(sourceId?: SourceIdentifier) {
         if (sourceId && sourceId !== this.__currentReflectionId) {
-            if(debug) console.log("Not disabling reflection for", sourceId, "because it is not the current light settings id", this.__currentReflectionId)
+            if (debug) console.log("Not disabling reflection for", sourceId, "because it is not the current light settings id", this.__currentReflectionId)
             return;
         }
         if (debug) console.log("Disable reflection", sourceId)

package/src/engine/engine_texture.ts

@@ -1,6 +1,6 @@
 import type { EffectComposer } from "postprocessing";
 import { Camera, Mesh, Object3D, Texture, WebGLRenderer, WebGLRenderTarget } from "three";
-import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer";
+import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
 
 import { findResourceUsers } from "./engine_assetdatabase.js";
 

package/src/engine/engine_tonemapping.ts

@@ -1,7 +1,7 @@
 import { ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping, NoToneMapping, ShaderChunk, ToneMapping } from "three";
 
 import { isDevEnvironment } from "./debug/index.js";
-import type { Context } from "./engine_setup";
+import type { Context } from "./engine_setup.js";
 
 let patchedTonemapping = false;
 export function patchTonemapping(_ctx?: Context) {

package/src/engine/engine_types.ts

@@ -566,6 +566,23 @@ export interface IPhysicsEngine {
      */
     boxOverlap(point: Vector3, size: Vector3, rotation: Vector4Like | null): Array<ShapeOverlapResult>;
 
+    /**
+     * Creates a collider in the physics world.
+     * 
+     * @param collider - The collider component.
+     * @param desc - The collider description.
+     * @returns The created collider.
+     * 
+     * @throws Will throw an error if the physics world is not initialized. Make sure to call `initialize()` before creating colliders.
+     * 
+     * @example
+     * ```typescript
+     * const boxColliderDesc = NEEDLE_ENGINE_MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.cuboid(1, 1, 1);
+     * const collider = physicsEngine.createCollider(myBoxColliderComponent, boxColliderDesc);
+     * ```
+     */
+    createCollider(collider: ICollider, desc: any): any;
+
     // Collider methods
     /**
      * Adds a sphere collider to the physics world

package/src/engine/engine_typestore.ts

@@ -7,6 +7,7 @@ declare type Type = new (...args: any[]) => any;
 class _TypeStore {
 
     private _types: Map<string, Type> = new Map();
+    private _reverseTypes: Map<Type, string> = new Map();
 
     constructor() {
         if (debug) console.warn("TypeStore: Created", this);
@@ -18,8 +19,10 @@ class _TypeStore {
     public add(key: string, type: Type) {
         if (debug) console.warn("ADD TYPE", key);
         const existing = this._types.get(key);
-        if (!existing)
+        if (!existing) {
             this._types.set(key, type);
+            this._reverseTypes.set(type, key);
+        }
         else {
             if (debug) {
                 if (existing !== type) {
@@ -40,11 +43,7 @@ class _TypeStore {
      * @returns the key/name for the given type if registered
      */
     public getKey(type: Type): string | null {
-        for (const [key, value] of this._types) {
-            if (value === type)
-                return key;
-        }
-        return null;
+        return this._reverseTypes.get(type) || null;
     }
 }
 

package/src/engine/extensions/NEEDLE_lightmaps.ts

@@ -95,8 +95,8 @@ export class NEEDLE_lightmaps implements GLTFLoaderPlugin {
                     }
                     const results = await PromiseAllWithErrors(dependencies);
                     if (results?.anyFailed) {
-                        if (isDevEnvironment())
-                            console.error("Failed to load lightmap extension", results);
+                        if (isDevEnvironment() || debug)
+                            console.error("[NEEDLE_lightmaps]Error during extension loading:", results);
                     }
                     resolve();
                 });

package/src/engine/extensions/extensions.ts

@@ -92,18 +92,24 @@ class PointerResolver {
     }
 }
 
-export async function registerExtensions(loader: GLTFLoader, context: Context, url: string) {
+export async function registerExtensions(loader: GLTFLoader, context: Context, url: string, sourceId: SourceIdentifier) {
 
     // Make sure to remove any url parameters from the sourceId (because the source id in the renderer does not have a ?v=xxx so it will not be able to register the resolved lightmap otherwise)
     const idEnd = url.indexOf("?");
     if (idEnd >= 0) url = url.substring(0, idEnd);
+    if (!sourceId) {
+        sourceId = url;
+    }
+    if (sourceId.startsWith("blob:") || sourceId.startsWith("data:")) {
+        console.debug("[GLTFLoader] Suspicious sourceId detected");
+    }
 
     loader.register(p => new NEEDLE_gameobject_data(p));
     loader.register(p => new NEEDLE_persistent_assets(p));
-    loader.register(p => new NEEDLE_lightmaps(p, context.lightmaps, url));
-    loader.register(p => new NEEDLE_lighting_settings(p, url, context));
-    loader.register(p => new NEEDLE_techniques_webgl(p, url));
-    loader.register(p => new NEEDLE_render_objects(p, url));
+    loader.register(p => new NEEDLE_lightmaps(p, context.lightmaps, sourceId));
+    loader.register(p => new NEEDLE_lighting_settings(p, sourceId, context));
+    loader.register(p => new NEEDLE_techniques_webgl(p, sourceId));
+    loader.register(p => new NEEDLE_render_objects(p, sourceId));
     loader.register(p => new NEEDLE_progressive(p));
     loader.register(p => new EXT_texture_exr(p));
     if (isResourceTrackingEnabled()) loader.register(p => new InternalUsageTrackerPlugin(p))

package/src/engine/webcomponents/logo-element.ts

@@ -2,6 +2,16 @@ import { madeWithNeedleSVG, needleLogoOnlySVG, needleLogoSVG } from "../assets/i
 
 const elementName = "needle-logo-element";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-logo-element": NeedleLogoElement;
+    }
+}
+
+/**
+ * Needle logo web component used in the hosting UI (small, compact logo or full)
+ * @element needle-logo-element
+ */
 export class NeedleLogoElement extends HTMLElement {
 
     static get elementName() { return elementName; }
@@ -83,10 +93,12 @@ export class NeedleLogoElement extends HTMLElement {
     private readonly wrapper: HTMLDivElement;
     private readonly logoElement: HTMLImageElement;
 
+    /** Show or hide the logo element (used by the menu) */
     setLogoVisible(val: boolean) {
         this.logoElement.style.display = val ? "block" : "none";
     }
 
+    /** Switch the logo between full and compact versions */
     setType(type: "full" | "compact") {
         if (type === "full") {
             this.logoElement.src = needleLogoSVG;

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -9,6 +9,12 @@ import { getIconElement } from "../icons.js";
 import { NeedleLogoElement } from "../logo-element.js";
 import { NeedleSpatialMenu } from "./needle-menu-spatial.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-logo-element": NeedleLogoElement;
+    }
+}
+
 const elementName = "needle-menu";
 const debug = getParam("debugmenu");
 const debugNonCommercial = getParam("debugnoncommercial");
@@ -264,6 +270,16 @@ export class NeedleMenu {
 
 }
 
+/**
+ * `<needle-menu>` web component — lightweight menu used by Needle Engine.
+ *
+ * This element is intended as an internal UI primitive for hosting application
+ * menus and buttons. Use the higher-level `NeedleMenu` API from the engine
+ * code to manipulate it programmatically. Public DOM-facing methods are
+ * documented (appendChild / append / prepend / setPosition / setVisible).
+ *
+ * @element needle-menu
+ */
 export class NeedleMenuElement extends HTMLElement {
 
     static create() {
@@ -851,6 +867,7 @@ export class NeedleMenuElement extends HTMLElement {
         }
     }
 
+    /** @private user preference for logo visibility */
     private _userRequestedLogoVisible?: boolean = undefined;
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
@@ -891,6 +908,7 @@ export class NeedleMenuElement extends HTMLElement {
         this.root.classList.add(position);
     }
 
+    /** @private user preference for menu visibility */
     private _userRequestedMenuVisible?: boolean = undefined;
     setVisible(visible: boolean) {
         this._userRequestedMenuVisible = visible;
@@ -905,14 +923,17 @@ export class NeedleMenuElement extends HTMLElement {
     }
 
     // private _root: ShadowRoot | null = null;
+    /** @private root container element inside shadow DOM */
     private readonly root: HTMLDivElement;
-    /** wraps the whole content */
+    /** @private wraps the whole content (internal layout) */
     private readonly wrapper: HTMLDivElement;
-    /** contains the buttons and dynamic elements */
+    /** @private contains the buttons and dynamic elements */
     private readonly options: HTMLDivElement;
-    /** contains the needle-logo html element */
+    /** @private contains the needle-logo html element */
     private readonly logoContainer: HTMLDivElement;
+    /** @private compact menu button element */
     private readonly compactMenuButton: HTMLButtonElement;
+    /** @private foldout container used in compact mode */
     private readonly foldout: HTMLDivElement;
 
     append(...nodes: (string | Node)[]): void {

package/src/engine/webcomponents/needle-button.ts

@@ -2,6 +2,12 @@ import { isDevEnvironment } from "../debug/index.js";
 import { iconFontUrl, loadFont } from "./fonts.js";
 import { WebXRButtonFactory } from "./WebXRButtons.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-button": NeedleButtonElement;
+    }
+}
+
 const htmlTagName = "needle-button";
 const isDev = isDevEnvironment();
 

package/src/engine/webcomponents/needle-engine.attributes.ts

@@ -28,6 +28,14 @@ type MainAttributes = {
 
     addEventListener?(event: "ready", callback: (event: CustomEvent) => void): void;
     addEventListener?(event: "error", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "loadstart", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "progress", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "loadfinished", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "xr-session-ended", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "enter-ar", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "exit-ar", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "enter-vr", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "exit-vr", callback: (event: CustomEvent) => void): void;
 }
 
 type LoadingAttributes = {
@@ -47,7 +55,7 @@ type SkyboxAttributes = {
     /** @deprecated. Use background-image instead - URL to .exr, .hdr, .png, .jpg to be used as skybox */
     "skybox-image"?: string,
     /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
-    "background-image"?: string, 
+    "background-image"?: string,
     /** Blurs the background image (if any) - value between 0 and 1  
      * 0: no blur
      * 1: full blur
@@ -69,16 +77,17 @@ type RenderingAttributes = {
     "transparent"?: boolean,
     "contactshadows"?: boolean,
     "tone-mapping"?: TonemappingAttributeOptions,
+    "tonemapping"?: TonemappingAttributeOptions,
     "tone-mapping-exposure"?: number,
 }
 
 /**
- * Available attributes for the `<needle-engine>` web component
+ * Available attributes for the `<needle-engine>` web component.
  * @inheritdoc
  */
 export type NeedleEngineAttributes =
     MainAttributes
-    & Partial<Omit<HTMLElement, "style">>
+    // & Partial<Omit<HTMLElement, "style">>
     & LoadingAttributes
     & SkyboxAttributes
     & RenderingAttributes

package/src/engine/webcomponents/needle-engine.ts

@@ -16,6 +16,12 @@ import { arContainerClassName, AROverlayHandler } from "./needle-engine.ar-overl
 import { NeedleEngineAttributes, TonemappingAttributeOptions } from "./needle-engine.attributes.js";
 import { calculateProgress01, EngineLoadingView, type ILoadingViewHandler } from "./needle-engine.loading.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-engine": NeedleEngineWebComponent;
+    }
+}
+
 // registering loader here too to make sure it's imported when using engine via vanilla js
 registerLoader(NeedleLoader);
 
@@ -55,17 +61,17 @@ const observedAttributes = [
 // https://developers.google.com/web/fundamentals/web-components/customelements
 
 /** 
- * <needle-engine> web component. See {@link NeedleEngineAttributes} attributes for supported attributes    
- * The needle engine web component creates and manages a needle engine context which is responsible for rendering a 3D scene using threejs.   
- * The needle engine context is created when the src attribute is set and disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
- * The needle engine context is accessible via the context property on the needle engine element (e.g. document.querySelector("needle-engine").context).
+ * The `<needle-engine>` web component. See {@link NeedleEngineAttributes} attributes for supported attributes    
+ * The web component creates and manages a Needle Engine context, which is responsible for rendering a 3D scene using threejs.   
+ * The context is created when the `src` attribute is set, and disposed when the element is removed from the DOM. You can prevent cleanup by setting the `keep-alive` attribute to `true`.  
+ * The context is accessible from the `<needle-engine>` element: `document.querySelector("needle-engine").context`.
  * See {@link https://engine.needle.tools/docs/reference/needle-engine-attributes}
  *
  * @example
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
  * @example
  * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
-*/
+ */
 export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
 
     static get observedAttributes() {
@@ -100,7 +106,6 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         else this.setAttribute("camera-controls", value ? "true" : "false");
     }
 
-
     /**
      * Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.  
      * The context is disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
@@ -133,7 +138,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     private _loadingProgress01: number = 0;
     private _loadingView?: ILoadingViewHandler;
     private _previousSrc: string | null | string[] = null;
-    /** set to true after <needle-engine> did load completely at least once. Set to false when <needle-engine> is removed from the document */
+    /** @private set to true after <needle-engine> did load completely at least once. Set to false when < to false when <needle-engine> is removed from the document removed from the document */
     private _didFullyLoad: boolean = false;
 
     constructor() {
@@ -296,6 +301,10 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         }
     }
 
+    connectedMoveCallback() {
+        // we dont want needle-engine to cleanup JUST because the element is moved in the DOM. See https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+    }
+
     /**
      * @internal
      */
@@ -317,7 +326,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             case "loadfinished":
                 if (typeof newValue === "string" && newValue.length > 0) {
                     if (debug) console.log(name + " attribute changed", newValue);
-                    this.registerEventFromAttribute(name, newValue);
+                    this.registerEventFromAttribute("loadfinished", newValue);
                 }
                 break;
             case "dracoDecoderPath":
@@ -441,7 +450,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (allowOverridingDefaultLoading) {
             // Handle the <needle-engine hide-loading-overlay> attribute
             const hideOverlay = this.getAttribute("hide-loading-overlay");
-            if (hideOverlay !== null && hideOverlay !== undefined && hideOverlay !== "0") {
+            if (hideOverlay !== null && hideOverlay !== undefined && (hideOverlay as any) !== "0") {
                 useDefaultLoading = false;
             }
         }
@@ -668,7 +677,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (attributeValue)
             this.registerEventFromAttribute("loadstart", attributeValue);
     }
-    private registerEventFromAttribute(eventName: string, code: string) {
+    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart', code: string) {
         const prev = this._previouslyRegisteredMap.get(eventName);
         if (prev) {
             this._previouslyRegisteredMap.delete(eventName);
@@ -681,6 +690,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
                 // const fn = new Function(newValue);
                 if (typeof fn === "function") {
                     this._previouslyRegisteredMap.set(eventName, fn);
+                    // @ts-ignore // not sure how to type this properly
                     this.addEventListener(eventName, evt => fn?.call(globalThis, this._context, evt));
                 }
             }
@@ -828,15 +838,157 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             setKtx2TranscoderPath(customKtx2DecoderPath);
         }
     }
+
+    /** Change which model gets loaded. This will trigger a reload of the model. */
+    setAttribute(name: 'src', value: string | string[]): void;
+    /** Optional string that will be applied to the context as a hash and can influence caching/identification. */
+    setAttribute(name: 'hash', value: string): void;
+    /** Public key used for licensing and feature gating (read-only on runtime if compiled-in). */
+    setAttribute(name: 'public-key', value: string): void;
+    /** Engine version string — usually set by the build/runtime. */
+    setAttribute(name: 'version', value: string): void;
+    /** If set to false the camera controls are disabled. Accepted values: true/false/none. Default behaviour is enabled. */
+    setAttribute(name: 'camera-controls', value: string): void;
+    /** Override path for the Draco decoder files. */
+    setAttribute(name: 'dracoDecoderPath', value: string): void;
+    /** Choose Draco decoder type: 'wasm' or 'js'. */
+    setAttribute(name: 'dracoDecoderType', value: 'wasm' | 'js'): void;
+    /** Override path for the KTX2 transcoder/decoder files. */
+    setAttribute(name: 'ktx2DecoderPath', value: string): void;
+    /** Tonemapping mode. Accepted values: 'none' | 'linear' | 'agx' | 'neutral'. */
+    setAttribute(name: 'tone-mapping', value: 'none' | 'linear' | 'agx' | 'neutral'): void;
+    /** Numeric exposure multiplier for tonemapping; accepts number or stringified number. */
+    setAttribute(name: 'tone-mapping-exposure', value: string | number): void;
+    /** Background image blur strength (0..1). Accepts number or string value. */
+    setAttribute(name: 'background-blurriness', value: string | number): void;
+    /** CSS color for the background; string color value expected (e.g. '#fff', 'rgba()' etc). */
+    setAttribute(name: 'background-color', value: string): void;
+    /** Intensity multiplier for environment lighting; accepts numeric value or string. */
+    setAttribute(name: 'environment-intensity', value: string | number): void;
+    /** When true the engine context is kept alive after the element is removed from DOM. Use 'true' or 'false'. */
+    setAttribute(name: 'keep-alive', value: 'true' | 'false'): void;
+    /** Generic typed setter for known Needle Engine attributes (useful from TS):
+     *  setAttribute<T extends keyof NeedleEngineAttributes>(name, value) will type-check against the declared attribute shape.
+     */
+    setAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T, value: NeedleEngineAttributes[T]): void;
+    setAttribute(qualifiedName: ({} & string), value: string): void;
+    setAttribute(qualifiedName: string, value: string): void {
+        super.setAttribute(qualifiedName, value);
+    }
+
+    /** Read the `src` attribute. Returns string, string[] (if codegen provided an array) or null if unset. */
+    getAttribute(name: 'src'): string | string[] | null;
+    /** Read the `hash` attribute — an optional string attached to the context for caching/identification. */
+    getAttribute(name: 'hash'): string | null;
+    /** Read the `public-key` attribute used for licensing/feature gating. */
+    getAttribute(name: 'public-key'): string | null;
+    /** Read the `version` attribute — the engine build/version string. */
+    getAttribute(name: 'version'): string | null;
+    /** Read the `camera-controls` attribute; string values include 'true'|'false'|'none' or null if unset. */
+    getAttribute(name: 'camera-controls'): string | null;
+    /** Read custom Draco decoder path if configured. */
+    getAttribute(name: 'dracoDecoderPath'): string | null;
+    /** Read Draco decoder type ('wasm'|'js') if configured. */
+    getAttribute(name: 'dracoDecoderType'): string | null;
+    /** Read custom KTX2 decoder/transcoder path if configured. */
+    getAttribute(name: 'ktx2DecoderPath'): string | null;
+    /** Read configured tone-mapping value, as a string matching accepted modes (none, linear, neutral, agx). */
+    getAttribute(name: 'tone-mapping'): string | null;
+    /** Read tone-mapping exposure multiplier (string or numeric string). */
+    getAttribute(name: 'tone-mapping-exposure'): string | null;
+    /** Read background-blurriness value (0..1) as string or null. */
+    getAttribute(name: 'background-blurriness'): string | null;
+    /** Read CSS background-color string value (e.g. '#fff', 'rgba()'). */
+    getAttribute(name: 'background-color'): string | null;
+    /** Read environment-intensity (numeric) as string or null. */
+    getAttribute(name: 'environment-intensity'): string | null;
+    /** Read keep-alive attribute; presence ("true") prevents the context from being disposed on disconnect. */
+    getAttribute(name: 'keep-alive'): string | null;
+    /** Defines a CSS selector or HTMLElement used to define the camera focus rectangle. */
+    getAttribute(name: 'focus-rect'): string | null;
+    /** @private */
+    getAttribute(name: 'loading-blur'): string | null;
+    /** @private */
+    getAttribute(name: 'alias'): string | null;
+    /** Typed getter for known NeedleEngine attribute names; returns the typed shape declared in NeedleEngineAttributes or null. */
+    getAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T): NeedleEngineAttributes[T] | null;
+    // getAttribute(qualifiedName: ({} & string)): string | null
+    getAttribute(qualifiedName: ({} & string)): string | null;
+    getAttribute(qualifiedName: string): string | null {
+        return super.getAttribute(qualifiedName);
+    }
+
+    /**
+     * Emitted when loading begins for the engine/scene. The event is cancelable — calling preventDefault() 
+     * will stop the default loading UI behavior (apps can implement custom loading flows).
+    * Event contains a small detail object with context and optional alias.
+     */
+    addEventListener(type: 'loadstart', listener: (ev: CustomEvent<{ context: Context; alias: string | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Emitted repeatedly while loading resources. Use the event detail to show progress: 
+    * Event contains progress metadata to report loader state.
+     */
+    addEventListener(type: 'progress', listener: (ev: CustomEvent<{ context: Context; name: string; progress: ProgressEvent<EventTarget>; index: number; count: number; totalProgress01: number }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Emitted when the initial loading has finished. detail contains the context, the source alias (if available) and a list of loaded models.
+    * Emitted when the initial load completes; contains helpful summary data.
+     */
+    addEventListener(type: 'loadfinished', listener: (ev: CustomEvent<{ context: Context; src: string | null; loadedFiles: LoadedModel[] }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when an XR session ends.
+     */
+    addEventListener(type: 'xr-session-ended', listener: (ev: CustomEvent<{ session: XRSession | null; context: Context; sessionMode: XRSessionMode | undefined }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when entering AR.
+     */
+    addEventListener(type: 'enter-ar', listener: (ev: CustomEvent<{ session: XRSession; context: Context; htmlContainer: HTMLElement | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when exiting AR.
+     */
+    addEventListener(type: 'exit-ar', listener: (ev: CustomEvent<{ session: XRSession; context: Context; htmlContainer: HTMLElement | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when entering VR.
+     */
+    addEventListener(type: 'enter-vr', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when exiting VR.
+     */
+    addEventListener(type: 'exit-vr', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when the engine has rendered its first frame and is ready. */
+    addEventListener(type: 'ready', listener: (ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when an XR session is started — useful to prepare AR/VR UI. */
+    addEventListener(type: 'xr-session-started', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+
+    // Sadly not enough to make types work (see comment below)
+    addEventListener<K extends keyof HTMLElementEventMap>(type: ({} & K), listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    // These are from the super type. Not sure how we can remove intellisense for the "regular" events while still making the types work...
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+
+    addEventListener(type: string, listener: any, options?: boolean | AddEventListenerOptions): void
+    {
+        return super.addEventListener(type, listener as EventListenerOrEventListenerObject, options);
+    }
 }
 
 if (typeof window !== "undefined" && !window.customElements.get(htmlTagName))
     window.customElements.define(htmlTagName, NeedleEngineWebComponent);
 
+/** Usage of the types declared above */
 
+const elem = document.querySelector("needle-engine")!;
+elem.setAttribute("src", "model.glb");
+elem.addEventListener("loadfinished", (ev) => {
+    const context = ev.detail.context;
+});
+elem.setAttribute("dracoDecoderType", "wasm");
+elem.addEventListener("enter-ar", (ev) => {
+    const session = ev.detail.session;
+});
 
-
-
+elem.addEventListener("mousedown", (ev) => {
+    console.log("regular mousedown event", ev);
+});
 
 function getDisplayName(str: string) {
     if (str.startsWith("blob:")) {
@@ -956,4 +1108,4 @@ function handleLoadingBlur(needleEngineElement: NeedleEngineWebComponent) {
             }
         }
     }, { once: true });
-}
+}

package/src/engine/xr/NeedleXRSession.ts

@@ -527,7 +527,9 @@ export class NeedleXRSession implements INeedleXRSession {
         else
             console.log("%c" + `Requesting ${mode} session`, "font-weight:bold;");
         for (const script of scripts) {
-            if (script.onBeforeXR) script.onBeforeXR(mode, init);
+            if (script.onBeforeXR && script.activeAndEnabled && !script.destroyed) {
+                script.onBeforeXR(mode, init);
+            }
         }
         for (const listener of this._sessionRequestStartListeners) {
             listener({ mode, init });