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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "5.1.0-alpha.4",
+  "version": "5.1.0-alpha.5",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {

package/plugins/common/cloud.js

@@ -1,2 +1,7 @@
 
-export const NEEDLE_CLOUD_CLI_NAME = "needle-cloud@version-1";
+const defaultVersion = "version-1";
+const version = process.env.NEEDLE_CLOUD_CLI_VERSION_OVERRIDE || defaultVersion;
+if (process.env.NEEDLE_CLOUD_CLI_VERSION_OVERRIDE) {
+    console.warn(`\n⚠️  WARNING: NEEDLE_CLOUD_CLI_VERSION_OVERRIDE is set to "${process.env.NEEDLE_CLOUD_CLI_VERSION_OVERRIDE}" — using needle-cloud@${version} instead of the default needle-cloud@${defaultVersion}.\n   This should only be used for hotfixes!\n`);
+}
+export const NEEDLE_CLOUD_CLI_NAME = `needle-cloud@${version}`;

package/plugins/vite/license.js

@@ -9,6 +9,7 @@ import { loadConfig } from './config.js';
  */
 export function needleLicense(command, config, userSettings) {
     let license = undefined;
+    let appliedLicense = false;
 
     return {
         name: "needle:license",
@@ -31,7 +32,15 @@ export function needleLicense(command, config, userSettings) {
 
         },
         async transform(src, id) {
-            const isNeedleEngineFile = id.includes("engine/engine_license") || id.includes("needle-tools_engine");
+            if (appliedLicense === true) {
+                return;
+            }
+
+            // 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) {
@@ -44,12 +53,21 @@ export function needleLicense(command, config, userSettings) {
                 if (index >= 0) {
                     const end = src.indexOf(";", index);
                     if (end >= 0) {
+                        appliedLicense = true;
                         const line = src.substring(index, end);
                         const replaced = "NEEDLE_ENGINE_LICENSE_TYPE = \"" + license + "\"";
                         src = src.replace(line, replaced);
                         return { code: src, map: null }
                     }
                 }
+                // @TODO: detect local needle engine dev setup and log error if not found
+            }
+        },
+        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";
 

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;
 

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_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

package/src/engine/engine_physics_rapier.ts

@@ -402,11 +402,16 @@ export class RapierPhysics implements IPhysicsEngine {
         filterGroups?: number,
         /** Return false to ignore this collider */
         filterPredicate?: (c: ICollider) => boolean,
-        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast) 
+        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast)
          * If not set the raycast will ignore objects in the IgnoreRaycast layer (default: true)
-         * @default undefined 
+         * @default undefined
         */
-        useIgnoreRaycastLayer?: boolean
+        useIgnoreRaycastLayer?: boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     })
         : null | { point: Vector3, collider: ICollider } {
 
@@ -428,6 +433,8 @@ export class RapierPhysics implements IPhysicsEngine {
 
         const hit = this.world?.castRay(ray, maxDistance, solid, options?.queryFilterFlags, options?.filterGroups, undefined, undefined, (c) => {
             const component = c[$componentKey];
+            // Skip trigger/sensor colliders unless explicitly included
+            if (options?.includeTriggers !== true && component?.isTrigger) return false;
             if (options?.filterPredicate) return options.filterPredicate(component);
             if (options?.useIgnoreRaycastLayer !== false) {
                 // ignore objects in the IgnoreRaycast=2 layer
@@ -453,11 +460,16 @@ export class RapierPhysics implements IPhysicsEngine {
         filterGroups?: number,
         /** Return false to ignore this collider */
         filterPredicate?: (c: ICollider) => boolean,
-        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast) 
+        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast)
          * If not set the raycast will ignore objects in the IgnoreRaycast layer (default: true)
-         * @default undefined 
+         * @default undefined
         */
-        useIgnoreRaycastLayer?: boolean
+        useIgnoreRaycastLayer?: boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     })
         : null | { point: Vector3, normal: Vector3, collider: ICollider } {
 
@@ -478,6 +490,8 @@ export class RapierPhysics implements IPhysicsEngine {
 
         const hit = this.world?.castRayAndGetNormal(ray, maxDistance, solid, options?.queryFilterFlags, options?.filterGroups, undefined, undefined, (c) => {
             const component = c[$componentKey];
+            // Skip trigger/sensor colliders unless explicitly included
+            if (options?.includeTriggers !== true && component?.isTrigger) return false;
             if (options?.filterPredicate) return options.filterPredicate(component);
             if (options?.useIgnoreRaycastLayer !== false) {
                 // ignore objects in the IgnoreRaycast=2 layer

package/src/engine/engine_types.ts

@@ -521,20 +521,25 @@ export interface IPhysicsEngine {
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** 
-         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
-         * The scene query will only consider hits with colliders with collision groups compatible with 
+        /**
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query.
+         * The scene query will only consider hits with colliders with collision groups compatible with
          * this collision group (using the bitwise test described in the collision groups section).
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002
          * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
          */
         filterGroups?: number,
-        /** 
+        /**
          * Predicate to filter colliders in raycast results
          * @param collider The collider being tested
          * @returns False to ignore this collider, true to include it
          */
-        filterPredicate?: (collider: ICollider) => boolean
+        filterPredicate?: (collider: ICollider) => boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     }): RaycastResult;
 
     /**
@@ -549,20 +554,25 @@ export interface IPhysicsEngine {
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** 
-         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
-         * The scene query will only consider hits with colliders with collision groups compatible with 
+        /**
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query.
+         * The scene query will only consider hits with colliders with collision groups compatible with
          * this collision group (using the bitwise test described in the collision groups section).
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002
          * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
          */
         filterGroups?: number,
-        /** 
+        /**
          * Predicate to filter colliders in raycast results
          * @param collider The collider being tested
          * @returns False to ignore this collider, true to include it
          */
-        filterPredicate?: (collider: ICollider) => boolean
+        filterPredicate?: (collider: ICollider) => boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     }): RaycastResult;
 
     /**