@needle-tools/engine 5.0.2 → 5.1.0-canary.87c4c44

package/src/engine/engine_animation.ts

@@ -2,9 +2,10 @@ import { AnimationAction, AnimationClip, AnimationMixer, KeyframeTrack, Object3D
 
 import { isDevEnvironment } from "./debug/index.js";
 import type { Context } from "./engine_context.js";
-import { GLTF, IAnimationComponent, Model } from "./engine_types.js";
+import { IAnimationComponent, Model } from "./engine_types.js";
 import { TypeStore } from "./engine_typestore.js";
 
+// #region Registry
 /**
  * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.  
  * Can be accessed from {@link Context.animations} and is used internally e.g. when exporting GLTF files.
@@ -52,10 +53,11 @@ export class AnimationsRegistry {
 }
 
 
+// #region Animation Utils
 /**
  * Utility class for working with animations.
  */
-export class AnimationUtils {
+export namespace AnimationUtils {
 
     /**
      * Tests if the root object of an AnimationAction can be animated. Objects where matrixAutoUpdate or matrixWorldAutoUpdate is set to false may not animate correctly.
@@ -63,7 +65,7 @@ export class AnimationUtils {
      * @param allowLog Whether to allow logging warnings. Default is false, which only allows logging in development environments.
      * @returns True if the root object can be animated, false otherwise
      */
-    static testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean {
+    export function testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean {
         const root = action.getRoot();
 
         if (root && (root.userData.static || root.matrixAutoUpdate === false || root.matrixWorldAutoUpdate === false)) {
@@ -79,13 +81,15 @@ export class AnimationUtils {
      * @param mixer The animation mixer to get the actions from
      * @returns The actions or null if the mixer is invalid
      */
-    static tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null {
+
+    export function tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null {
         const actions = mixer["_actions"] as Array<AnimationAction>;
         if (!actions) return null;
         return actions;
     }
 
-    static tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip> {
+
+    export function tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip> {
         if (!target) target = new Array<AnimationClip>();
 
         if (!obj) {
@@ -96,18 +100,49 @@ export class AnimationUtils {
         }
         if (obj.children) {
             for (const child of obj.children) {
-                this.tryGetAnimationClipsFromObjectHierarchy(child, target);
+                tryGetAnimationClipsFromObjectHierarchy(child, target);
             }
         }
         return target;
     }
 
+
+    const $objectAnimationKey = Symbol("objectIsAnimatedData");
+
+    /** Internal method - This marks an object as being animated. Make sure to always call isAnimated=false if you stop animating the object
+     * @param obj The object to mark
+     * @param isAnimated Whether the object is animated or not
+     */
+    export function setObjectAnimated(obj: Object3D, animatedBy: object, isAnimated: boolean) {
+        if (!obj) return;
+        if (obj[$objectAnimationKey] === undefined) {
+            if (!isAnimated) return;
+            obj[$objectAnimationKey] = new Set<object>();
+        }
+
+        const set = obj[$objectAnimationKey] as Set<object>;
+        if (isAnimated) {
+            set.add(animatedBy);
+        }
+        else if (set.has(animatedBy))
+            set.delete(animatedBy);
+    }
+
+    /** Get is the object is currently animated. Currently used by the Animator to check if a timeline animationtrack is actively animating an object */
+    export function getObjectAnimated(obj: Object3D): boolean {
+        if (!obj) return false;
+        const set = obj[$objectAnimationKey] as Set<object>;
+        return set !== undefined && set.size > 0;
+    }
+
+    // #region Autoplay
     /**
      * Assigns animations from a GLTF file to the objects in the scene.  
      * This method will look for objects in the scene that have animations and assign them to the correct objects.  
      * @param file The GLTF file to assign the animations from
      */
-    static autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null {
+
+    export function autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null {
         if (!file || !file.animations) {
             console.debug("No animations found in file");
             return null;
@@ -171,11 +206,14 @@ export class AnimationUtils {
     }
 
 
-    static emptyClip(): AnimationClip {
+    // #region Create Clips
+
+    export function emptyClip(): AnimationClip {
         return new AnimationClip("empty", 0, []);
     }
 
-    static createScaleClip(options?: ScaleClipOptions): AnimationClip {
+
+    export function createScaleClip(options?: ScaleClipOptions): AnimationClip {
         const duration = options?.duration ?? 0.3;
 
         let baseScale: Vector3Like = { x: 1, y: 1, z: 1 };

package/src/engine/engine_components.ts

@@ -1,4 +1,5 @@
 import { Object3D, Scene } from "three";
+import { v5 } from 'uuid';
 
 import { ComponentLifecycleEvents } from "./engine_components_internal.js";
 import { activeInHierarchyFieldName } from "./engine_constants.js";
@@ -6,8 +7,35 @@ import { removeScriptFromContext, updateActiveInHierarchyWithoutEventCall } from
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
 import { Context, registerComponent } from "./engine_setup.js";
 import type { ComponentInit, Constructor, ConstructorConcrete, IComponent, IGameObject } from "./engine_types.js";
+import { $componentName } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
 import { apply } from "./js-extensions/index.js";
+import { TypeStore } from "./engine_typestore.js";
+
+const COMPONENT_GUID_NAMESPACE = 'eff8ba80-635d-11ec-90d6-0242ac120003';
+
+/**
+ * Generates a deterministic guid for a component based on the object's guid and the component type.
+ * If the object has a guid, the component guid is derived from `objectGuid:TypeName:index`
+ * using UUID v5 hashing. This ensures the same component type added to the same object on
+ * different clients gets the same guid — critical for networked components like SyncedTransform.
+ * Falls back to the shared counter-based IdProvider if the object has no guid.
+ */
+function generateDeterministicComponentGuid(obj: Object3D, component: IComponent): string {
+    const objectGuid = obj["guid"];
+    if (objectGuid) {
+        const typeName = component[$componentName] ?? component.constructor?.name ?? "Component";
+        // Count existing components of same type for uniqueness (e.g. multiple of the same component type)
+        const existingComponents = getComponents(obj, component.constructor as any);
+        let sameTypeCount = 0;
+        for (const c of existingComponents) {
+            if (c !== component) sameTypeCount++;
+        }
+        const key = `${objectGuid}:${typeName}:${sameTypeCount}`;
+        return v5(key, COMPONENT_GUID_NAMESPACE);
+    }
+    return getIdProvider().generateUUID();
+}
 
 
 const debug = getParam("debuggetcomponent");
@@ -57,9 +85,8 @@ export function addNewComponent<T extends IComponent>(obj: Object3D, componentIn
     if (!obj.userData.components) obj.userData.components = [];
     obj.userData.components.push(componentInstance);
     componentInstance.gameObject = obj as IGameObject;
-    // TODO: currently add component does not ensure a new component instance has a guid
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
-        componentInstance.guid = getIdProvider().generateUUID();
+        componentInstance.guid = generateDeterministicComponentGuid(obj, componentInstance);
     }
     apply(obj);
     // register the component - make sure to provide the component instance context (if assigned)
@@ -109,9 +136,9 @@ export function addComponent<T extends IComponent>(obj: Object3D, componentInsta
     // componentInstance.__internalEnable();
     // componentInstance.transform = obj;
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
-        componentInstance.guid = getIdProvider().generateUUID();
+        componentInstance.guid = generateDeterministicComponentGuid(obj, componentInstance);
     }
-    if(init) componentInstance._internalInit(init);
+    if (init) componentInstance._internalInit(init);
     // Register the component - make sure to provide the component instance context (if assigned)
     registerComponent(componentInstance, componentInstance.context);
     return componentInstance;
@@ -144,10 +171,12 @@ function onGetComponent<T>(obj: Object3D | null | undefined, componentType: Cons
     }
     if (!(obj?.userData?.components)) return null;
     if (typeof componentType === "string") {
-        if (!didWarnAboutComponentAccess) {
+        const type = TypeStore.get(componentType);
+        if (!didWarnAboutComponentAccess && !type) {
             didWarnAboutComponentAccess = true;
             console.warn(`Accessing components by name is not supported.\nPlease use the component type instead. This may keep working in local development but it will fail when bundling your application.\n\nYou can import other modules your main module to get access to types\nor if you use npmdefs you can make types available globally using globalThis:\nhttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis`, componentType);
         }
+        if (type) componentType = type as Constructor<T>;
     }
 
     if (debugEnabled())
@@ -222,7 +251,7 @@ export function getComponents<T extends IComponent>(obj: Object3D, componentType
  * ```
  */
 export function getComponentInChildren<T extends IComponent>(obj: Object3D, componentType: Constructor<T>, includeInactive: boolean = false): T | null {
-    if (includeInactive === false && obj[activeInHierarchyFieldName] === false) return null; 
+    if (includeInactive === false && obj[activeInHierarchyFieldName] === false) return null;
     const res = getComponent(obj, componentType) as IComponent | null;
     if (includeInactive === false && (res?.enabled === false || res?.activeAndEnabled === false)) return null;
     if (res) return res as T;
@@ -335,7 +364,7 @@ export function findObjectOfType<T extends IComponent>(type: Constructor<T>, con
     if (!scene) return null;
 
     const res = getComponentInChildren(scene, type, includeInactive);
-    if(res) return res;
+    if (res) return res;
     return null;
 }
 

package/src/engine/engine_context.ts

@@ -43,6 +43,7 @@ import { patchTonemapping } from './engine_tonemapping.js';
 import type { CoroutineData, ICamera, IComponent, IContext, ILight, LoadedModel, Model, SourceIdentifier, Vec2 } from "./engine_types.js";
 import { deepClone, delay, DeviceUtilities, getParam } from './engine_utils.js';
 import type { INeedleXRSessionEventReceiver, NeedleXRSession } from './engine_xr.js';
+import { PostProcessing } from './postprocessing/index.js';
 import { NeedleMenu } from './webcomponents/needle menu/needle-menu.js';
 import type { NeedleEngineWebComponent } from './webcomponents/needle-engine.js';
 
@@ -387,9 +388,11 @@ export class Context implements IContext {
 	 */
 	renderer!: WebGLRenderer;
 	/**
-	 * The effect composer can be used to render postprocessing effects. If assigned then it will automatically render the scene every frame.
+	 * The effect composer used for rendering postprocessing effects.
+	 * @deprecated Use `context.postprocessing.composer` instead.
 	 */
-	composer: EffectComposer | ThreeEffectComposer | null = null;
+	get composer(): EffectComposer | ThreeEffectComposer | null { return this.postprocessing.composer; }
+	set composer(value: EffectComposer | ThreeEffectComposer | null) { this.postprocessing.composer = value; }
 
 	// #region internal script lists
 	/**
@@ -504,6 +507,8 @@ export class Context implements IContext {
 	input: Input;
 	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
 	physics: Physics;
+	/** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
+	postprocessing: PostProcessing;
 	/** access networking methods (use it to send or listen to messages or join a networking backend) */
 	connection: NetworkConnection;
 	/**  @deprecated AssetDatabase is deprecated */
@@ -564,6 +569,7 @@ export class Context implements IContext {
 		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();
@@ -1778,6 +1784,9 @@ export class Context implements IContext {
 		if (this.renderer.toneMapping !== NoToneMapping)
 			patchTonemapping(this);
 
+		// Update postprocessing stack (applies dirty effects, adaptive multisampling/pixel ratio)
+		this.postprocessing.update();
+
 		if (this.composer && !this.isInXR) {
 			// if a camera is passed in we need to check if we need to update the composer's camera
 			if (camera && "setMainCamera" in this.composer) {

package/src/engine/engine_gameobject.ts

@@ -8,6 +8,7 @@ import { activeInHierarchyFieldName } from "./engine_constants.js";
 import { editorGuidKeyName } from "./engine_constants.js";
 import { $isUsingInstancing, InstancingUtil } from "./engine_instancing.js";
 import { processNewScripts } from "./engine_mainloop_utils.js";
+import type { syncInstantiate } from "./engine_networking_instantiate.js";
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
 import { assign, ISerializable } from "./engine_serialization_core.js";
 import { Context, registerComponent } from "./engine_setup.js";
@@ -19,7 +20,11 @@ import { apply } from "./js-extensions/index.js";
 const debug = getParam("debuggetcomponent");
 const debugInstantiate = getParam("debuginstantiate");
 
+/**
+ * Options for instantiating a GameObject, used in {@link instantiate} and {@link syncInstantiate}
+ */
 export type IInstantiateOptions = {
+    /** The ID provider for generating unique IDs / guids */
     idProvider?: UIDProvider;
     //** parent guid or object */
     parent?: string | Object3D;

package/src/engine/engine_init.ts

@@ -12,6 +12,7 @@ import { patchLayers } from "./js-extensions/Layers.js";
 import { initObject3DExtensions } from "./js-extensions/Object3D.js";
 import { initVectorExtensions } from "./js-extensions/Vector.js";
 import { initWebComponents } from "./webcomponents/init.js";
+import { initXR } from "./xr/init.js";
 
 let initialized = false;
 
@@ -42,4 +43,5 @@ export function initEngine() {
     initAnimationAutoplay();
     initSkyboxAttributes();
     initSceneSwitcherAttributes();
+    initXR();
 }

package/src/engine/engine_input.ts

@@ -1088,7 +1088,8 @@ export class Input implements IInput {
         if (this.context.isInAR) return;
         if (this.canReceiveInput(evt) === false) return;
         if (evt.target instanceof HTMLElement) {
-            evt.target.setPointerCapture(evt.pointerId);
+            try { evt.target.setPointerCapture(evt.pointerId); }
+            catch { /* may fail during pointer lock */ }
         }
         const id = this.getPointerId(evt);
         if (debug) showBalloonMessage(`pointer down #${id}, identifier:${evt.pointerId}`);

package/src/engine/engine_materialpropertyblock.ts

@@ -560,25 +560,6 @@ const $savedTextureTransforms = Symbol("savedTextureTransforms");
  */
 type ObjectRenderCallback = (this: Object3D, renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
 
-/**
- * Collect all materials from an object and its children
- * @internal
- */
-function collectMaterials(object: Object3D, materials: Set<Material>): void {
-    const obj = object as Object3D & { material?: Material | Material[] };
-    if (obj.material) {
-        if (Array.isArray(obj.material)) {
-            obj.material.forEach(mat => materials.add(mat));
-        } else {
-            materials.add(obj.material);
-        }
-    }
-
-    // For Groups, collect materials from children too
-    if (object.type === "Group") {
-        object.children.forEach(child => collectMaterials(child, materials));
-    }
-}
 
 /**
  * Find property block by checking this object and parent (if parent is a Group).
@@ -626,7 +607,7 @@ const beforeRenderListTransparentChangedTransmission = new WeakMap<Object3D, num
  * @internal
  */
 const onBeforeRenderListPush = function (this: Object3D, _object: Object3D, _geometry: BufferGeometry, material: Material, _group: Group) {
-    const block = registry.getBlock(_object);
+    const block = findPropertyBlockAndOwner(this)?.block;
     if (!block) {
         return;
     }

package/src/engine/engine_networking.ts

@@ -248,6 +248,7 @@ export class OwnershipModel {
     private _gainSubscription: (response: GainedOwnershipBroadcastResponse) => void;
     private _lostSubscription: (guid: string) => void;
     private _hasOwnerResponse: (response: OwnershipResponse) => void;
+    private _pendingOwnershipResolve: ((value: boolean) => void) | null = null;
 
     constructor(connection: NetworkConnection, guid: string) {
         this.connection = connection;
@@ -291,7 +292,6 @@ export class OwnershipModel {
     }
 
     private waitForHasOwnershipRequestResponse(res: OwnershipResponse) {
-        // console.log(res);
         if (res.guid === this.guid) {
             if (this._isWaitingForOwnershipResponseCallback) {
                 this.connection.stopListen(OwnershipEvent.ResponseHasOwner, this._isWaitingForOwnershipResponseCallback);
@@ -301,47 +301,58 @@ export class OwnershipModel {
             if (!res.value) {
                 if (debugOwner)
                     console.log("request ownership", this.guid)
-                this.requestOwnership();
+                this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
             }
         }
     }
 
 
+
     /**
      * Requests ownership and waits asynchronously until ownership is granted or timeout occurs.
      * @returns Promise that resolves with this OwnershipModel when ownership is gained
      * @throws Rejects with "Timeout" if ownership is not gained within ~1 second
      * @example
      * ```ts
-     * try {
-     *   await ownership.requestOwnershipAsync();
+     * const owned = await ownership.requestOwnership();
+     * if (owned) {
      *   // Ownership granted, safe to modify object
-     * } catch(e) {
-     *   console.warn("Could not gain ownership:", e);
      * }
      * ```
      */
-    public requestOwnershipAsync(): Promise<OwnershipModel> {
-        return new Promise((resolve, reject) => {
-            this.requestOwnership();
-            let updates = 0;
-            const waitForOwnership = () => {
-                if (updates++ > 10) return reject("Timeout");
-                setTimeout(() => {
-                    if (this.hasOwnership) resolve(this);
-                    else waitForOwnership();
-                }, 100);
-            };
-            waitForOwnership();
+    /**
+     * Requests ownership of this object from the networking server.
+     * Returns a Promise that resolves with `true` when ownership is granted, or `false` on timeout/failure.
+     * If ownership is already held, resolves immediately with `true`.
+     * @returns Promise that resolves with `true` if ownership was gained, `false` otherwise
+     */
+    public requestOwnership(): Promise<boolean> {
+        if (this._hasOwnership) return Promise.resolve(true);
+
+        // Cancel any previous pending request
+        this._pendingOwnershipResolve?.(false);
+        this._pendingOwnershipResolve = null;
+
+        if (debugOwner) console.log("Request ownership", this.guid);
+        this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
+
+        return new Promise((resolve) => {
+            this._pendingOwnershipResolve = resolve;
+
+            // Timeout after ~2 seconds
+            setTimeout(() => {
+                if (this._pendingOwnershipResolve === resolve) {
+                    this._pendingOwnershipResolve = null;
+                    resolve(false);
+                }
+            }, 2000);
         });
     }
 
     /**
-     * Requests ownership of this object from the networking server.
-     * Ownership may not be granted immediately - check `hasOwnership` property or use `requestOwnershipAsync()`.
-     * @returns this OwnershipModel instance for method chaining
+     * @deprecated Use `requestOwnership()` instead for a more reliable way to gain ownership
      */
-    public requestOwnership(): OwnershipModel {
+    public async requestOwnershipAsync(): Promise<OwnershipModel> {
         if (debugOwner) console.log("Request ownership", this.guid);
         this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
         return this;
@@ -374,16 +385,23 @@ export class OwnershipModel {
             this.connection.stopListen(OwnershipEvent.ResponseHasOwner, this._isWaitingForOwnershipResponseCallback);
             this._isWaitingForOwnershipResponseCallback = null;
         }
+        // Clean up pending ownership request
+        this._pendingOwnershipResolve?.(false);
+        this._pendingOwnershipResolve = null;
     }
 
     private onGainedOwnership(res: GainedOwnershipBroadcastResponse) {
         if (res.guid === this.guid) {
             this._isOwned = true;
-            // console.log(res.owner, connection.connectionId)
             if (this.connection.connectionId === res.owner) {
                 if (debugOwner)
                     console.log("GAINED OWNERSHIP", this.guid)
                 this._hasOwnership = true;
+                // Resolve pending ownership request
+                if (this._pendingOwnershipResolve) {
+                    this._pendingOwnershipResolve(true);
+                    this._pendingOwnershipResolve = null;
+                }
             }
             else this._hasOwnership = false;
         }
@@ -394,6 +412,11 @@ export class OwnershipModel {
                 console.log("LOST OWNERSHIP", this.guid)
             this._hasOwnership = false;
             this._isOwned = false;
+            // Resolve pending ownership request as failed
+            if (this._pendingOwnershipResolve) {
+                this._pendingOwnershipResolve(false);
+                this._pendingOwnershipResolve = null;
+            }
         }
     }
 }