@needle-tools/engine 3.28.5-beta → 3.28.6-beta

package/src/engine/engine_serialization_builtin_serializer.ts

@@ -215,6 +215,7 @@ declare type EventListCall = {
     method: string,
     target: string,
     argument?: any,
+    arguments?: Array<any>,
     enabled?: boolean,
 }
 
@@ -280,14 +281,22 @@ class EventListSerializer extends TypeSerializer {
                         }
                     }
 
-                    let args = call.argument;
-                    if (args !== undefined) {
-                        if (typeof args === "object") {
+                    function deserializeArgument(arg: any) {
+                        if (typeof arg === "object") {
                             // Try to deserialize the call argument to either a object or a component reference
-                            let argRes = objectSerializer.onDeserialize(call.argument, context);
-                            if (!argRes) argRes = componentSerializer.onDeserialize(call.argument, context);
-                            if (argRes) args = argRes;
+                            let argRes = objectSerializer.onDeserialize(arg, context);
+                            if (!argRes) argRes = componentSerializer.onDeserialize(arg, context);
+                            if (argRes) return argRes;
                         }
+                        return arg;
+                    }
+
+                    let args = call.argument;
+                    if (args !== undefined) {
+                        args = deserializeArgument(args);
+                    }
+                    else if (call.arguments !== undefined) {
+                        args = call.arguments.map(deserializeArgument);
                     }
 
                     // This is the final method we pass to the call info (or undefined if the method couldnt be resolved)
@@ -326,8 +335,17 @@ class EventListSerializer extends TypeSerializer {
         return (...forwardedArgs) => {
             const method = target[methodName];
             if (typeof method === "function") {
-                if (args !== undefined)
-                    method?.call(target, args);
+                if (args !== undefined) {
+                    // we now have support for creating event methods with multiple arguments
+                    // an argument can not be an array right now - so if we receive an array we assume it's the array of arguments that we want to call the method with
+                    // this means ["test", true] will invoke the method like this: myFunction("test", true) 
+                    if (Array.isArray(args))
+                        method?.call(target, ...args);
+                    // in any other case (when we just have one argument) we just call the method with the argument
+                    // we an not use ...args by default becaue that would break string arguments (it would then just use the first character)
+                    else
+                        method?.call(target, args);
+                }
                 else // support invoking EventList with any number of arguments (if none were declared in unity)
                     method?.call(target, ...forwardedArgs);
             }
@@ -357,7 +375,7 @@ export class RenderTextureSerializer extends TypeSerializer {
                 colorSpace: THREE.LinearSRGBColorSpace,
             });
             rt.texture = tex;
-            
+
             tex.isRenderTargetTexture = true;
             tex.flipY = true;
             tex.offset.y = 1;

package/src/engine/engine_three_utils.ts

@@ -236,6 +236,17 @@ export function logHierarchy(root: Object3D | null | undefined, collapsible: boo
     };
 }
 
+export function getParentHierarchyPath(obj: Object3D): string {
+    let path = obj?.name || "";
+    if(!obj) return path;
+    let parent = obj.parent;
+    while (parent) {
+        path = parent.name + "/" + path;
+        parent = parent.parent;
+    }
+    return path;
+}
+
 
 export function isAnimationAction(obj: object) {
     if (obj) {

package/src/engine/engine_types.ts

@@ -101,10 +101,14 @@ export declare interface INeedleEngineComponent extends HTMLElement {
 }
 
 export declare interface IGameObject extends Object3D {
+
+    /** the object's unique identifier */
     guid: string | undefined;
 
+    /** if the object is enabled in the hierarchy (usually equivalent to `visible`) */
     activeSelf: boolean;
 
+    /** call to destroy this object including all components that are attached to it. Will destroy all children recursively */
     destroy(): void;
 
     /** NOTE: this is just a wrapper for devs coming from Unity. Please use this.gameObject instead. In Needle Engine this.gameObject is the same as this.gameObject.transform. See the tutorial link below for more information
@@ -113,14 +117,26 @@ export declare interface IGameObject extends Object3D {
      * */
     get transform(): IGameObject;
 
+    /** Add a new component to this object. Expects a component type (e.g. `addNewComponent(Animator)`) */
     addNewComponent<T>(type: Constructor<T>): T | null;
+    /** Remove a component from this object. Expected a component instance
+     * @returns the removed component (equal to the passed in component)
+     */
     removeComponent(comp: IComponent): IComponent;
+    /** Searches for a component type on this object. If no component of the searched type exists yet a new instance will be created and returned */
     getOrAddComponent<T>(typeName: Constructor<T> | null): T;
+    /** Tries to find a component of a type on this object. 
+     * @returns the first instance of a component on this object that matches the passed in type or null if no component of this type (or a subtype) exists */
     getComponent<T>(type: Constructor<T>): T | null;
+    /** @returns all components of a certain type on this object */
     getComponents<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+    /** Finds a component of a certain type on this object OR a child object if any exists */
     getComponentInChildren<T>(type: Constructor<T>): T | null;
+    /** Finds all components of a certain type on this object AND all children (recursively) */
     getComponentsInChildren<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+    /** Finds a component of a certain type on this object OR a parent object if any exists */
     getComponentInParent<T>(type: Constructor<T>): T | null;
+    /** Finds all components of a certain type on this object AND all parents (recursively) */
     getComponentsInParent<T>(type: Constructor<T>, arr?: T[]): Array<T>;
 
     get worldPosition(): Vector3;
@@ -144,6 +160,7 @@ export interface IHasGuid {
 export interface IComponent extends IHasGuid {
     get isComponent(): boolean;
 
+    /** the object this component is attached to */
     gameObject: IGameObject;
     // guid: string;
     enabled: boolean;
@@ -327,7 +344,9 @@ export class ContactPoint {
     private readonly _normal: Vec3;
     private readonly _tangentVelocity: Vec3;
 
+    /** the distance of the collision point */
     readonly distance: number;
+    /** the impulse velocity */
     readonly impulse: number;
     readonly friction: number;
 
@@ -343,7 +362,7 @@ export class ContactPoint {
         return target.set(this._normal.x, this._normal.y, this._normal.z);
     }
 
-    /** */
+    /** worldspace tangent */
     get tangentVelocity() {
         const target = contactsVectorBuffer.get();
         return target.set(this._tangentVelocity.x, this._tangentVelocity.y, this._tangentVelocity.z);
@@ -361,55 +380,36 @@ export class ContactPoint {
 
 /// all info in here must be readonly because the object is only created once per started collision
 export class Collision {
+
+    /** The contact points of this collision. Contains information about positions, normals, distance, friction, impulse... */
     readonly contacts: ContactPoint[];
 
-    constructor(obj: Object3D, otherCollider: ICollider, contacts: ContactPoint[]) {
+    constructor(obj: IGameObject, otherCollider: ICollider, contacts: ContactPoint[]) {
         this.me = obj;
         this._collider = otherCollider;
         this._gameObject = otherCollider.gameObject;
         this.contacts = contacts;
     }
 
-    readonly me: Object3D;
-    private _collider: ICollider;
+    /** the gameobject this collision event belongs to (e.g. if onCollisionEnter is called then `me` is the same as `this.gameObject`) */
+    readonly me: IGameObject;
 
-    /** the collider the collision happened with */
+    private _collider: ICollider;
+    /** the other collider the collision happened with */
     get collider(): ICollider {
         return this._collider;
     }
 
-    /** the object the collision happened with */
-    private _gameObject: Object3D;
-    get gameObject(): Object3D {
+    private _gameObject: IGameObject;
+    /** the other object the collision happened with */
+    get gameObject(): IGameObject {
         return this._gameObject;
     }
 
-    /** the rigidbody we hit, null if none attached */
+    /** the other rigidbody we hit, null if none attached */
     get rigidBody(): IRigidbody | null {
         return this.collider?.attachedRigidbody;
     }
-
-
-
-    // private _normal?: Vector3;
-    // get normal(): Vector3 {
-    //     if (!this._normal) {
-    //         const vec = this.collision.contact.ni;
-    //         this._normal = new Vector3(vec.x, vec.y, vec.z);
-    //     }
-    //     return this._normal;
-    // }
-
-
-    // private _point?: Vector3;
-    // get point(): Vector3 {
-    //     if (!this._point) {
-    //         const c = this.collision.contact;
-    //         const point = c.bi.position.clone().vadd(c.ri);
-    //         this._point = new Vector3(point.x, point.y, point.z);
-    //     }
-    //     return this._point;
-    // }
 }
 
 export type RaycastResult = null | { point: Vector3, collider: ICollider, normal?: Vector3 };

package/src/engine-components/Animator.ts

@@ -87,7 +87,8 @@ export class Animator extends Behaviour {
     /**@deprecated use setBool */
     SetBool(name: string | number, val: boolean) { this.setBool(name, val); }
     setBool(name: string | number, value: boolean) {
-        if(this.runtimeAnimatorController?.getBool(name) !== value)
+        if (debug) console.log("setBool", name, value);
+        if (this.runtimeAnimatorController?.getBool(name) !== value)
             this._parametersAreDirty = true;
         this.runtimeAnimatorController?.setBool(name, value);
     }
@@ -95,55 +96,71 @@ export class Animator extends Behaviour {
     /**@deprecated use getBool */
     GetBool(name: string | number) { return this.getBool(name); }
     getBool(name: string | number): boolean {
-        return this.runtimeAnimatorController?.getBool(name) ?? false;
+        const res = this.runtimeAnimatorController?.getBool(name) ?? false;
+        if (debug) console.log("getBool", name, res);
+        return res;
+    }
+
+    toggleBool(name: string | number) {
+        this.setBool(name, !this.getBool(name));
     }
 
     /**@deprecated use setFloat */
     SetFloat(name: string | number, val: number) { this.setFloat(name, val); }
     setFloat(name: string | number, val: number) {
-        if(this.runtimeAnimatorController?.getFloat(name) !== val)
+        if (this.runtimeAnimatorController?.getFloat(name) !== val)
             this._parametersAreDirty = true;
+        if (debug) console.log("setFloat", name, val);
         this.runtimeAnimatorController?.setFloat(name, val);
     }
 
     /**@deprecated use getFloat */
     GetFloat(name: string | number) { return this.getFloat(name); }
     getFloat(name: string | number): number {
-        return this.runtimeAnimatorController?.getFloat(name) ?? -1;
+        const res = this.runtimeAnimatorController?.getFloat(name) ?? -1;
+        if (debug) console.log("getFloat", name, res);
+        return res;
     }
 
     /**@deprecated use setInteger */
     SetInteger(name: string | number, val: number) { this.setInteger(name, val); }
     setInteger(name: string | number, val: number) {
-        if(this.runtimeAnimatorController?.getInteger(name) !== val)
+        if (this.runtimeAnimatorController?.getInteger(name) !== val)
             this._parametersAreDirty = true;
+        if (debug) console.log("setInteger", name, val);
         this.runtimeAnimatorController?.setInteger(name, val);
     }
 
     /**@deprecated use getInteger */
     GetInteger(name: string | number) { return this.getInteger(name); }
     getInteger(name: string | number): number {
-        return this.runtimeAnimatorController?.getInteger(name) ?? -1;
+        const res = this.runtimeAnimatorController?.getInteger(name) ?? -1;
+        if (debug) console.log("getInteger", name, res);
+        return res;
     }
 
     /**@deprecated use setTrigger */
     SetTrigger(name: string | number) { this.setTrigger(name); }
     setTrigger(name: string | number) {
-        this.runtimeAnimatorController?.setTrigger(name);
         this._parametersAreDirty = true;
+        if (debug) console.log("setTrigger", name);
+        this.runtimeAnimatorController?.setTrigger(name);
     }
 
     /**@deprecated use resetTrigger */
     ResetTrigger(name: string | number) { this.resetTrigger(name); }
     resetTrigger(name: string | number) {
-        this.runtimeAnimatorController?.resetTrigger(name);
         this._parametersAreDirty = true;
+        if (debug) console.log("resetTrigger", name);
+        this.runtimeAnimatorController?.resetTrigger(name);
     }
 
     /**@deprecated use getTrigger */
     GetTrigger(name: string | number) { this.getTrigger(name); }
     getTrigger(name: string | number) {
-        this.runtimeAnimatorController?.getTrigger(name);
+        const res = this.runtimeAnimatorController?.getTrigger(name);
+        if (debug) console.log("getTrigger", name, res);
+        return res;
     }
 
     /**@deprecated use isInTransition */
@@ -156,6 +173,7 @@ export class Animator extends Behaviour {
     SetSpeed(speed: number) { return this.setSpeed(speed); }
     setSpeed(speed: number) {
         if (speed === this.speed) return;
+        if (debug) console.log("setSpeed", speed);
         this.speed = speed;
         this._animatorController?.setSpeed(speed);
     }

package/src/engine-components/RigidBody.ts

@@ -115,6 +115,7 @@ class TransformWatch {
         const original = this.obj.matrixWorld.multiplyMatrices.bind(this.obj.matrixWorld);
         const lastParentMatrix = new Matrix4();
         this.obj.matrixWorld["multiplyMatrices"] = (parent: Matrix4, matrix: Matrix4) => {
+            if (this.context.physics.engine?.isUpdating || this.mute) return original(parent, matrix);
             if (!lastParentMatrix.equals(parent)) {
                 this.positionChanged = true;
                 this.rotationChanged = true;