@needle-tools/engine 5.1.0-alpha.4 → 5.1.0-alpha.6

package/plugins/common/license.js

@@ -86,24 +86,38 @@ async function requestNeedleCloud(path, options) {
 
 /** @typedef {{ ok: boolean, status: number, statusText: string, text: string }} NeedleCloudHttpResponse */
 
+/** @typedef {{ type: string, jwt: string | null }} LicenseResult */
+
 /**
  * Replace license string - used for webpack
  * @param {string} code
  * @param {DefaultOptions & {accessToken?:string, team:string|undefined}} opts
  */
 export async function replaceLicense(code, opts) {
-    const index = code?.indexOf("NEEDLE_ENGINE_LICENSE_TYPE");
+    const index = code?.indexOf("EzdGPQg");
     if (index >= 0) {
-        const licenseType = await resolveLicense(opts);
-        if (!licenseType) {
+        const licenseResult = await resolveLicense(opts);
+        if (!licenseResult) {
             return code;
         }
         const end = code.indexOf(";", index);
         if (end >= 0) {
             const line = code.substring(index, end);
-            const replaced = "NEEDLE_ENGINE_LICENSE_TYPE = \"" + licenseType + "\"";
+            const replaced = "EzdGPQg = \"" + licenseResult.type + "\"";
             code = code.replace(line, replaced);
-            return code;
+        }
+
+        // Also inject JWT if available
+        if (licenseResult.jwt) {
+            const jwtIndex = code.indexOf("_$InwX");
+            if (jwtIndex >= 0) {
+                const jwtEnd = code.indexOf(";", jwtIndex);
+                if (jwtEnd >= 0) {
+                    const jwtLine = code.substring(jwtIndex, jwtEnd);
+                    const jwtReplaced = "_$InwX = \"" + licenseResult.jwt + "\"";
+                    code = code.replace(jwtLine, jwtReplaced);
+                }
+            }
         }
     }
     return code;
@@ -112,7 +126,7 @@ export async function replaceLicense(code, opts) {
 /**
  * Resolve the license using the needle engine licensing server
  * @param {DefaultOptions & {accessToken?:string, team?:string} | null} args
- * @returns {Promise<string | null>}
+ * @returns {Promise<LicenseResult | null>}
  */
 export async function resolveLicense(args = null) {
     let accessToken = args?.accessToken;
@@ -226,10 +240,11 @@ export async function resolveLicense(args = null) {
 /**
  * @param {string} str License string
  * @param {{includeFetchLine?: boolean}} [options]
+ * @returns {LicenseResult | null}
  */
 function tryParseLicense(str, options = undefined) {
     try {
-        /** @type {{needle_engine_license:string}} */
+        /** @type {{needle_engine_license:string, needle_license_jwt?:string}} */
         const licenseJson = JSON.parse(str);
         if (licenseJson.needle_engine_license) {
             const success = `INFO: Successfully received \"${licenseJson.needle_engine_license?.toUpperCase()}\" license`;
@@ -239,7 +254,10 @@ function tryParseLicense(str, options = undefined) {
             else {
                 logLicense(success);
             }
-            return licenseJson.needle_engine_license;
+            return {
+                type: licenseJson.needle_engine_license,
+                jwt: licenseJson.needle_license_jwt || null,
+            };
         }
         if ("error" in licenseJson) {
             logLicense(`ERROR in license check: \"${licenseJson.error}\"`, "error");

package/plugins/vite/license.js

@@ -8,7 +8,9 @@ import { loadConfig } from './config.js';
  * @returns {import('vite').Plugin}
  */
 export function needleLicense(command, config, userSettings) {
-    let license = undefined;
+    /** @type {import('../common/license.js').LicenseResult | null | undefined} */
+    let licenseResult = undefined;
+    let appliedLicense = false;
 
     return {
         name: "needle:license",
@@ -23,7 +25,7 @@ export function needleLicense(command, config, userSettings) {
                 }
             }
 
-            license = await resolveLicense({
+            licenseResult = await resolveLicense({
                 team: team,
                 accessToken: userSettings?.license?.accessToken,
                 loglevel: userSettings?.debugLicense === true ? "verbose" : undefined
@@ -31,25 +33,58 @@ export function needleLicense(command, config, userSettings) {
 
         },
         async transform(src, id) {
-            const isNeedleEngineFile = id.includes("engine/engine_license") || id.includes("needle-tools_engine");
+            // Vite 4 and 8 handling:
+            const isNeedleEngineFile = id.includes("engine/engine_license")
+                || id.includes("needle-tools_engine")
+                || id.includes("@needle-tools")
+                || id.includes("needle-engine");
             // sometimes the actual license parameter is in a unnamed chunk file
             const isViteChunkFile = id.includes("chunk") && id.includes(".vite");
             if (isNeedleEngineFile || isViteChunkFile) {
 
-                if (!license) {
+                if (!licenseResult) {
                     return;
                 }
 
-                const index = src.indexOf("NEEDLE_ENGINE_LICENSE_TYPE");
+                let modified = false;
+
+                // Replace license type
+                const index = src.indexOf("EzdGPQg");
                 if (index >= 0) {
                     const end = src.indexOf(";", index);
                     if (end >= 0) {
                         const line = src.substring(index, end);
-                        const replaced = "NEEDLE_ENGINE_LICENSE_TYPE = \"" + license + "\"";
+                        const replaced = "EzdGPQg = \"" + licenseResult.type + "\"";
                         src = src.replace(line, replaced);
-                        return { code: src, map: null }
+                        modified = true;
                     }
                 }
+
+                // Replace license JWT (same pattern)
+                if (licenseResult.jwt) {
+                    const jwtIndex = src.indexOf("_$InwX");
+                    if (jwtIndex >= 0) {
+                        const jwtEnd = src.indexOf(";", jwtIndex);
+                        if (jwtEnd >= 0) {
+                            const jwtLine = src.substring(jwtIndex, jwtEnd);
+                            const jwtReplaced = "_$InwX = \"" + licenseResult.jwt + "\"";
+                            src = src.replace(jwtLine, jwtReplaced);
+                            modified = true;
+                        }
+                    }
+                }
+
+                if (modified) {
+                    appliedLicense = true;
+                    return { code: src, map: null }
+                }
+            }
+        },
+        buildEnd() {
+            if (!appliedLicense) {
+                if (process.env.NEEDLE_TEST_ENV) {
+                    console.error("ERR: License was not applied!");
+                }
             }
         }
     }

package/src/engine/api.ts

@@ -167,6 +167,9 @@ export * from "./engine_constants.js";
  */
 export * from "./engine_context.js";
 
+/** Typed event bus for decoupled component communication via {@link Context.events} */
+export * from "./engine_context_eventbus.js";
+
 /** Registry for managing multiple engine contexts */
 export * from "./engine_context_registry.js";
 
@@ -227,7 +230,7 @@ export * from "./engine_input.js";
 export { InstancingUtil } from "./engine_instancing.js";
 
 /** License checking utilities */
-export { hasCommercialLicense, hasIndieLicense, hasProLicense } from "./engine_license.js";
+export { LynjGsV, __otwqOR, _cxKhKwDL } from "./engine_license.js";
 
 
 // ============================================================================

package/src/engine/codegen/register_types.ts

@@ -101,12 +101,12 @@ import { TestRunner } from "../../engine-components/TestRunner.js";
 import { TestSimulateUserData } from "../../engine-components/TestRunner.js";
 import { PlayableDirector } from "../../engine-components/timeline/PlayableDirector.js";
 import { SignalReceiver } from "../../engine-components/timeline/SignalAsset.js";
-import { AnimationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { AudioTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { MarkerTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineAnimationTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineAudioTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineMarkerTrack } from "../../engine-components/timeline/TimelineTracks.js";
 import { SignalTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { ActivationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { ControlTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineActivationTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineControlTrack } from "../../engine-components/timeline/TimelineTracks.js";
 import { TransformGizmo } from "../../engine-components/TransformGizmo.js";
 import { BaseUIComponent } from "../../engine-components/ui/BaseUIComponent.js";
 import { UIRootComponent } from "../../engine-components/ui/BaseUIComponent.js";
@@ -257,12 +257,12 @@ export function initBuiltinTypes() {
 	TypeStore.add("TestSimulateUserData", TestSimulateUserData);
 	TypeStore.add("PlayableDirector", PlayableDirector);
 	TypeStore.add("SignalReceiver", SignalReceiver);
-	TypeStore.add("AnimationTrackHandler", AnimationTrackHandler);
-	TypeStore.add("AudioTrackHandler", AudioTrackHandler);
-	TypeStore.add("MarkerTrackHandler", MarkerTrackHandler);
+	TypeStore.add("TimelineAnimationTrack", TimelineAnimationTrack);
+	TypeStore.add("TimelineAudioTrack", TimelineAudioTrack);
+	TypeStore.add("TimelineMarkerTrack", TimelineMarkerTrack);
 	TypeStore.add("SignalTrackHandler", SignalTrackHandler);
-	TypeStore.add("ActivationTrackHandler", ActivationTrackHandler);
-	TypeStore.add("ControlTrackHandler", ControlTrackHandler);
+	TypeStore.add("TimelineActivationTrack", TimelineActivationTrack);
+	TypeStore.add("TimelineControlTrack", TimelineControlTrack);
 	TypeStore.add("TransformGizmo", TransformGizmo);
 	TypeStore.add("BaseUIComponent", BaseUIComponent);
 	TypeStore.add("UIRootComponent", UIRootComponent);

package/src/engine/engine_camera.fit.ts

@@ -257,12 +257,23 @@ export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnTyp
     else {
         direction.sub(camera.worldPosition);
     }
-    if (centerCamera === "y")
-        direction.y = 0;
+    if (centerCamera === "y") {
+        // Preserve the camera's current elevation angle when it's already above the center,
+        // but clamp to a minimum elevation to prevent the camera from ending up at or below
+        // the scene center (which causes a "looking up from below" effect).
+        // direction points FROM camera TO center, so negative Y = camera is above center.
+        const horizontalLen = Math.sqrt(direction.x * direction.x + direction.z * direction.z);
+        if (horizontalLen > 0.0001) {
+            const minY = -horizontalLen * verticalOffset * 4;
+            if (direction.y > minY) direction.y = minY;
+        }
+        else {
+            // Camera is directly above/below center — pick a default slight angle from +Z
+            direction.set(0, -verticalOffset * 4, 1);
+        }
+    }
     direction.normalize();
     direction.multiplyScalar(distance);
-    if (centerCamera === "y")
-        direction.y += -verticalOffset * 4 * distance;
 
     let cameraLocalPosition = center.clone().sub(direction);
     if (options.cameraOffset) {

package/src/engine/engine_context.ts

@@ -23,6 +23,7 @@ import { Application } from './engine_application.js';
 import { AssetDatabase } from './engine_assetdatabase.js';
 import { FocusRect, FocusRectSettings, updateCameraFocusRect } from './engine_camera.js';
 import { VERSION } from './engine_constants.js';
+import { EventBus } from './engine_context_eventbus.js';
 import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { WaitForPromise } from './engine_coroutine.js';
 import { ObjectUtils } from "./engine_create_objects.js";
@@ -151,7 +152,7 @@ export function registerComponent(script: IComponent, context?: Context) {
 }
 
 /**
- * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application. 
+ * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application.
  * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
  * 
  * The context is automatically created when using the `<needle-engine>` web component.  
@@ -522,19 +523,31 @@ export class Context implements IContext {
 	private _fallbackCamera: PerspectiveCamera | null = null;
 
 	/** access application state (e.g. if all audio should be muted) */
-	application: Application;
+	get application(): Application { return this._application; }
+	private _application!: Application;
 	/** access animation mixer used by components in the scene */
-	animations: AnimationsRegistry;
+	get animations(): AnimationsRegistry { return this._animations; }
+	private _animations!: AnimationsRegistry;
 	/** access timings (current frame number, deltaTime, timeScale, ...) */
-	time: Time;
+	get time(): Time { return this._time; }
+	private _time!: Time;
 	/** access input data (e.g. click or touch events) */
-	input: Input;
+	get input(): Input { return this._input; }
+	private _input!: Input;
 	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
-	physics: Physics;
+	get physics(): Physics { return this._physics; }
+	private _physics!: Physics;
 	/** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
-	postprocessing: PostProcessing;
+	get postprocessing(): PostProcessing { return this._postprocessing; }
+	private _postprocessing!: PostProcessing;
 	/** access networking methods (use it to send or listen to messages or join a networking backend) */
-	connection: NetworkConnection;
+	get connection(): NetworkConnection { return this._connection; }
+	private _connection!: NetworkConnection;
+	/** context-level event bus for decoupled component communication
+	 * @see {@link ContextEventMap} for known event types
+	 */
+	get events(): EventBus { return this._events; }
+	private _events = new EventBus();
 	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
 
@@ -606,12 +619,12 @@ export class Context implements IContext {
 		else this.scene = new Scene();
 		if (args?.camera) this._mainCamera = args.camera;
 
-		this.application = new Application(this);
-		this.time = new Time();
-		this.input = new Input(this);
-		this.physics = new Physics(this);
-		this.postprocessing = new PostProcessing(this);
-		this.connection = new NetworkConnection(this);
+		this._application = new Application(this);
+		this._time = new Time();
+		this._input = new Input(this);
+		this._physics = new Physics(this);
+		this._postprocessing = new PostProcessing(this);
+		this._connection = new NetworkConnection(this);
 		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		this.assets = new AssetDatabase();
 		this.sceneLighting = new SceneLighting(this);
@@ -620,7 +633,7 @@ export class Context implements IContext {
 		this.players = new PlayerViewManager(this);
 		this.menu = new NeedleMenu(this);
 		this.lodsManager = new LODsManager(this);
-		this.animations = new AnimationsRegistry(this);
+		this._animations = new AnimationsRegistry(this);
 		this.accessibility = new AccessibilityManager(this);
 
 
@@ -869,6 +882,8 @@ export class Context implements IContext {
 
 		this._onBeforeRenderListeners.clear();
 		this._onAfterRenderListeners.clear();
+		this._events.clear();
+		this._events = new EventBus();
 
 		this.lights.length = 0;
 
@@ -1793,6 +1808,7 @@ export class Context implements IContext {
 					? (`${((window.performance as any).memory.usedJSHeapSize / 1024 / 1024).toFixed(2)} MB`)
 					: "n/a";
 
+				const gl = this.renderer.getContext();
 				console.log(this.renderer.info.render.calls + " DrawCalls", "\nRender:",
 					{
 						shaders: this.renderer.info.programs?.length,
@@ -1802,7 +1818,16 @@ export class Context implements IContext {
 					{
 						usedMemory: usedJSHeapSize,
 						...this.renderer.info.memory
-					}, "\nTarget Framerate: " + this.targetFrameRate);
+					},
+					"\nRenderer:",
+					{
+						dpr: this.renderer.getPixelRatio(),
+						windowDpr: window.devicePixelRatio,
+						antialias: gl.getContextAttributes()?.antialias,
+						samples: gl.getParameter(gl.SAMPLES),
+						resolution: `${this.renderer.domElement.width}x${this.renderer.domElement.height}`,
+					},
+					"\nTarget Framerate: " + this.targetFrameRate);
 			}
 		}
 

package/src/engine/engine_context_eventbus.ts

@@ -0,0 +1,73 @@
+import type { Object3D } from "three";
+
+import type { IComponent } from "./engine_types.js";
+
+/** Typed event map for {@link Context.events}.
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
+ */
+export interface ContextEventMap {
+	"scene-content-changed": {
+		/** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
+		readonly source: IComponent;
+		/** The root object that was added/loaded */
+		readonly object: Object3D;
+	};
+}
+
+/** Options for {@link EventBus.on}. */
+export interface EventBusListenerOptions {
+	/** If true the listener is automatically removed after the first invocation. */
+	once?: boolean;
+}
+
+/** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
+ * Custom events can be typed at the call site via generic parameter.
+ * @example Known events
+ * ```ts
+ * context.events.on("scene-content-changed", e => e.object);
+ * ```
+ * @example Custom events — type at call site
+ * ```ts
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
+ * ```
+ * @example Once
+ * ```ts
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
+ * ```
+ */
+export class EventBus {
+	private _listeners = new Map<string, Function[]>();
+
+	/** Emit a known {@link ContextEventMap} event */
+	emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
+	/** Emit a custom event with user-provided type */
+	emit<T>(type: string, detail?: T): void;
+	emit(type: string, detail?: unknown): void {
+		const arr = this._listeners.get(type);
+		if (arr) for (const cb of [...arr]) cb(detail);
+	}
+
+	/** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
+	on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
+	/** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
+	on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
+	on(type: string, callback: Function, options?: EventBusListenerOptions): () => void {
+		let arr = this._listeners.get(type);
+		if (!arr) { arr = []; this._listeners.set(type, arr); }
+		const unsub = () => {
+			const i = arr.indexOf(wrapped);
+			if (i >= 0) arr.splice(i, 1);
+		};
+		const wrapped = options?.once
+			? (...args: unknown[]) => { unsub(); callback(...args); }
+			: callback;
+		arr.push(wrapped);
+		return unsub;
+	}
+
+	/** Remove all listeners. Called when the context is cleared or destroyed. */
+	clear(): void {
+		this._listeners.clear();
+	}
+}

package/src/engine/engine_init.ts

@@ -8,7 +8,7 @@ import { initBuiltinTypes } from "./codegen/register_types.js";
 import { initSpatialConsole } from "./debug/debug_spatial_console.js";
 import { initAddressableSerializers } from "./engine_addressables.js";
 import { ensureAudioContextIsResumed } from "./engine_audio.js";
-import { initLicense } from "./engine_license.js";
+import { _$AnFl } from "./engine_license.js";
 import { initNeedleLoader } from "./engine_loaders.js";
 import { initPhysics } from "./engine_physics_rapier.js";
 import { initBuiltinSerializers } from "./engine_serialization_builtin_serializer.js";
@@ -59,5 +59,5 @@ export function initEngine() {
     initPhysics();
     initXR();
     initSpatialConsole();
-    initLicense();
+    _$AnFl();
 }

package/src/engine/engine_input.ts

@@ -343,14 +343,33 @@ export class Input implements IInput {
     private readonly _eventListeners: Record<string, RegisteredEventListenerValue> = {};
 
     /** Adds an event listener for the specified event type. The callback will be called when the event is triggered.
+     *
+     * Returns an unsubscribe function — call it to remove the listener.
+     * Pass it to {@link Behaviour.autoCleanup} for automatic lifecycle management.
+     *
      * @param type The event type to listen for
      * @param callback The callback to call when the event is triggered
      * @param options The options for adding the event listener.
-     * @example Basic usage
+     * @returns A function that removes the event listener when called.
+     *
+     * @example With autoCleanup (recommended)
      * ```ts
-     * input.addEventListener("pointerdown", (evt) => {
+     * export class MyComponent extends Behaviour {
+     *   onEnable() {
+     *     this.autoCleanup(this.context.input.addEventListener("pointerdown", (evt) => {
+     *       console.log("Pointer down", evt.pointerId, evt.pointerType);
+     *     }));
+     *   }
+     *   // Listener is automatically removed on disable — no manual cleanup needed!
+     * }
+     * ```
+     * @example Manual unsubscribe
+     * ```ts
+     * const off = input.addEventListener("pointerdown", (evt) => {
      *   console.log("Pointer down", evt.pointerId, evt.pointerType);
      * });
+     * // later
+     * off();
      * ```
      * @example Adding a listener that is called after all other listeners
      * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).
@@ -366,14 +385,14 @@ export class Input implements IInput {
      * }, { once: true });
      * ```
      */
-    addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions);
-    addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions);
-    addEventListener(type: InputEvents | InputEventNames, callback: InputEventListener, options?: EventListenerOptions): void {
+    addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions): () => void;
+    addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions): () => void;
+    addEventListener(type: InputEvents | InputEventNames, callback: InputEventListener, options?: EventListenerOptions): () => void {
         if (!this._eventListeners[type]) this._eventListeners[type] = [];
 
         if (!callback || typeof callback !== "function") {
             console.error("Invalid call to addEventListener: callback is required and must be a function!");
-            return;
+            return () => {};
         }
 
         if (!options) options = {};
@@ -392,6 +411,8 @@ export class Input implements IInput {
         } else {
             queueListeners.listeners.push({ callback, options });
         }
+
+        return () => this.removeEventListener(type as any, callback as any, options);
     }
     /** Removes the event listener from the specified event type. If no queue is specified the listener will be removed from all queues.
      * @param type The event type to remove the listener from