@needle-tools/engine 2.39.0-pre → 2.40.0-pre

package/src/engine/engine_physics.ts

@@ -1,14 +1,16 @@
 import { BasicDepthPacking, Box3, BufferAttribute, BufferGeometry, Camera, Intersection, Layers, LineBasicMaterial, LineSegments, Matrix4, Mesh, NormalAnimationBlendMode, NumberKeyframeTrack, Object3D, Quaternion, Ray, Raycaster, Sphere, Vector2, Vector3 } from 'three'
 import { Context } from './engine_setup';
-import { getParam } from "./engine_utils"
-import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPositionXYZ, setWorldQuaternionXYZW } from "./engine_three_utils"
+import { CircularBuffer, getParam } from "./engine_utils"
+import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPositionXYZ, setWorldQuaternion, setWorldQuaternionXYZW } from "./engine_three_utils"
 import {
     IComponent,
     ICollider,
     IRigidbody,
     Collision,
     ContactPoint,
-    Vec3
+    Vec3,
+    IGameObject,
+    Vec2,
 } from './engine_types';
 import { InstancingUtil } from './engine_instancing';
 import { foreachComponent } from './engine_gameobject';
@@ -21,6 +23,7 @@ export type Rapier = typeof RAPIER;
 const debugPhysics = getParam("debugphysics");
 const debugColliderPlacement = getParam("debugphysicscolliders");
 const debugCollisions = getParam("debugcollisions");
+const showColliders = getParam("showcolliders");
 
 
 declare type PhysicsBody = {
@@ -28,7 +31,9 @@ declare type PhysicsBody = {
     rotation(): { x: number, y: number, z: number, w: number }
 }
 
+/** on physics body and references the needle component */
 const $componentKey = Symbol("needle component");
+/** on needle component and references physics body */
 const $bodyKey = Symbol("physics body");
 const $colliderRigidbody = Symbol("rigidbody");
 // const $removed = Symbol("removed");
@@ -75,6 +80,12 @@ export class SphereIntersection implements Intersection {
     }
 }
 
+declare type PhysicsRaycastResult = {
+    point: Vector3,
+    normal?: Vector3,
+    collider?: ICollider
+}
+
 export class Physics {
 
     // raycasting
@@ -140,6 +151,10 @@ export class Physics {
         return this.raycast(opts);
     }
 
+    /** raycast against rendered three objects. This might be very slow depending on your scene complexity.
+     * We recommend setting objects to IgnoreRaycast layer (2) when you don't need them to be raycasted.
+     * Raycasting SkinnedMeshes is specially expensive.
+     */
     public raycast(options: RaycastOptions | null = null): Array<Intersection> {
         if (!options) options = this.defaultRaycastOptions;
         const mp = options.screenPoint ?? this.context.input.mousePositionRC;
@@ -194,6 +209,7 @@ export class Physics {
         results.length = 0;
         rc.intersectObjects(targets, options.recursive, results);
 
+        // TODO: instead of doing this we should temporerly set these objects to layer 2 during raycasting
         const ignorelist = options.ignore;
         if (ignorelist !== undefined && ignorelist.length > 0) {
             results = results.filter(r => !ignorelist.includes(r.object));
@@ -201,8 +217,70 @@ export class Physics {
         return results;
     }
 
+    private rapierRay = new RAPIER.Ray({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 1 });
+    private raycastVectorsBuffer = new CircularBuffer(() => new Vector3(), 10);
 
+    /** raycast against colliders */
+    public raycastPhysicsFast(origin: Vec2 | Vec3, direction: Vec3 | undefined = undefined, maxDistance: number = Infinity, solid: boolean = true)
+        : null | { point: Vector3, collider:ICollider } {
 
+        const ray = this.getPhysicsRay(this.rapierRay, origin, direction);
+        if (!ray) return null;
+
+        const hit = this.world?.castRay(ray, maxDistance, solid);
+        if (hit) {
+            const point = ray.pointAt(hit.toi);
+            const vec = this.raycastVectorsBuffer.get();
+            vec.set(point.x, point.y, point.z);
+            return { point: vec, collider: hit.collider[$componentKey] };
+        }
+
+        return null;
+    }
+
+    private getPhysicsRay(ray: RAPIER.Ray, origin: Vec2 | Vec3, direction: Vec3 | undefined = undefined): RAPIER.Ray | null {
+        const cam = this.context.mainCamera;
+        // if we get origin in 2d space we need to project it to 3d space
+        if (origin["z"] === undefined) {
+            if (!cam) {
+                console.error("Can not perform raycast from 2d point - no main camera found");
+                return null;
+            }
+            const vec3 = this.raycastVectorsBuffer.get();
+            // if the origin is in screen space we need to convert it to raycaster space
+            if (origin.x > 1 || origin.y > 1 || origin.y < -1 || origin.x < -1) {
+                this.context.input.convertScreenspaceToRaycastSpace(origin);
+            }
+            vec3.set(origin.x, origin.y, -1);
+            vec3.unproject(cam);
+            origin = vec3;
+        }
+
+        const o = origin as Vec3;
+
+        ray.origin.x = o.x;
+        ray.origin.y = o.y;
+        ray.origin.z = o.z;
+        const vec = this.raycastVectorsBuffer.get();
+        if (direction)
+            vec.set(direction.x, direction.y, direction.z);
+        else {
+            if (!cam) {
+                console.error("Can not perform raycast - no camera found");
+                return null;
+            }
+            vec.set(ray.origin.x, ray.origin.y, ray.origin.z);
+            const camPosition = getWorldPosition(cam);
+            vec.sub(camPosition);
+        }
+        // we need to normalize the ray because our input is a max travel length and the direction may be not normalized
+        vec.normalize();
+        ray.dir.x = vec.x;
+        ray.dir.y = vec.y;
+        ray.dir.z = vec.z;
+        // Gizmos.DrawRay(ray.origin, ray.dir, 0xff0000, Infinity);
+        return ray;
+    }
 
     // physics simulation
 
@@ -514,7 +592,7 @@ export class Physics {
     }
 
     private updateDebugRendering(world: World) {
-        if (debugPhysics || debugColliderPlacement) {
+        if (debugPhysics || debugColliderPlacement || showColliders) {
             if (!this.lines) {
                 let material = new LineBasicMaterial({
                     color: 0xffffff,
@@ -661,22 +739,62 @@ export class Physics {
     private static centerConnectionPos = { x: 0, y: 0, z: 0 };
     private static centerConnectionRot = { x: 0, y: 0, z: 0, w: 1 };
 
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody, rel: { x: number, y: number, z: number }) {
+
+
+    addFixedJoint(body1: IRigidbody, body2: IRigidbody) {
         if (!this.world) {
             console.error("Physics world not initialized");
             return;
         }
         const b1 = body1[$bodyKey] as RigidBody;
         const b2 = body2[$bodyKey] as RigidBody;
-        const rot = body1.worldQuaternion.multiply(body2.worldQuaternion.invert());
+
+        this.calculateJointRelativeMatrices(body1.gameObject, body2.gameObject, this._tempMatrix);
+        this._tempMatrix.decompose(this._tempPosition, this._tempQuaternion, this._tempScale);
+
         const params = JointData.fixed(
             Physics.centerConnectionPos, Physics.centerConnectionRot,
-            rel, rot
+            this._tempPosition, this._tempQuaternion,
         );
         const joint = this.world.createImpulseJoint(params, b1, b2, true);
-        console.log("ADD JOINT", joint)
+        if (debugPhysics)
+            console.log("ADD FIXED JOINT", joint)
     }
 
+
+
+    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: { x: number, y: number, z: number }, axis: { x: number, y: number, z: number }) {
+        if (!this.world) {
+            console.error("Physics world not initialized");
+            return;
+        }
+        const b1 = body1[$bodyKey] as RigidBody;
+        const b2 = body2[$bodyKey] as RigidBody;
+
+        this.calculateJointRelativeMatrices(body1.gameObject, body2.gameObject, this._tempMatrix);
+        this._tempMatrix.decompose(this._tempPosition, this._tempQuaternion, this._tempScale);
+
+        let params = RAPIER.JointData.revolute(anchor, this._tempPosition, axis);
+        let joint = this.world.createImpulseJoint(params, b1, b2, true);
+        if (debugPhysics)
+            console.log("ADD HINGE JOINT", joint)
+    }
+
+
+    private calculateJointRelativeMatrices(body1: IGameObject, body2: IGameObject, mat: Matrix4) {
+        body1.updateWorldMatrix(true, false);
+        body2.updateWorldMatrix(true, false);
+        const world1 = body1.matrixWorld;
+        const world2 = body2.matrixWorld;
+        // set scale to 1
+        world1.elements[0] = 1;
+        world1.elements[5] = 1;
+        world1.elements[10] = 1;
+        world2.elements[0] = 1;
+        world2.elements[5] = 1;
+        world2.elements[10] = 1;
+        mat.copy(world2).premultiply(world1.invert()).invert();
+    }
 }
 
 
@@ -693,6 +811,7 @@ class PhysicsCollisionHandler {
     }
 
     private activeCollisions: Array<{ collider: ICollider, component: IComponent, collision: Collision }> = [];
+    private activeCollisionsStay: Array<{ collider: ICollider, component: IComponent, collision: Collision }> = [];
     private activeTriggers: Array<{ collider: ICollider, component: IComponent, otherCollider: ICollider }> = [];
 
     handleCollisionEvents() {
@@ -739,22 +858,32 @@ class PhysicsCollisionHandler {
             // TODO: we dont respect the flip value here!
             this.world.contactPair(selfBody, otherBody, (manifold, _flipped) => {
                 foreachComponent(object, (c: IComponent) => {
-                    if (c.onCollisionEnter) {
+                    if (c.onCollisionEnter || c.onCollisionStay || c.onCollisionExit) {
                         if (!collision) {
                             const contacts: Array<ContactPoint> = [];
                             const normal = manifold.normal();
-                            for (let i = 0; i < manifold.numContacts(); i++) {
-                                const pt1 = manifold.localContactPoint1(i);
-                                const dist = manifold.contactDist(i);
-                                if (pt1) {
-                                    const contact = new ContactPoint(pt1, dist, normal);
+                            for (let i = 0; i < manifold.numSolverContacts(); i++) {
+                                // solver points are in world space
+                                // https://rapier.rs/docs/user_guides/javascript/advanced_collision_detection_js#the-contact-graph
+                                const pt = manifold.solverContactPoint(i);
+                                const impulse = manifold.contactImpulse(i);
+                                if (pt) {
+                                    const dist = manifold.contactDist(i);
+                                    const friction = manifold.solverContactFriction(i);
+                                    const contact = new ContactPoint(pt, dist, normal, impulse, friction);
                                     contacts.push(contact);
                                 }
                             }
                             collision = new Collision(object, other, contacts);
                         }
-                        c.onCollisionEnter.call(c, collision);
-                        this.activeCollisions.push({ collider: self, component: c, collision });
+
+                        const info = { collider: self, component: c, collision };
+                        this.activeCollisions.push(info);
+                        if (c.onCollisionStay) {
+                            this.activeCollisionsStay.push(info);
+                        }
+
+                        c.onCollisionEnter?.call(c, collision);
                     }
                 });
             });
@@ -762,7 +891,7 @@ class PhysicsCollisionHandler {
     }
 
     private onHandleCollisionStay() {
-        for (const active of this.activeCollisions) {
+        for (const active of this.activeCollisionsStay) {
             const c = active.component;
             if (c.activeAndEnabled && c.onCollisionStay) {
                 const arg = active.collision;
@@ -792,6 +921,19 @@ class PhysicsCollisionHandler {
                 }
             }
         }
+        for (let i = 0; i < this.activeCollisionsStay.length; i++) {
+            const active = this.activeCollisionsStay[i];
+            const collider = active.collider;
+            if (collider === self && active.collision.collider === other) {
+                const c = active.component;
+                this.activeCollisionsStay.splice(i, 1);
+                i--;
+                if (c.activeAndEnabled && c.onCollisionExit) {
+                    const collision = active.collision;
+                    c.onCollisionExit(collision);
+                }
+            }
+        }
         for (let i = 0; i < this.activeTriggers.length; i++) {
             const active = this.activeTriggers[i];
             const collider = active.collider;

package/src/engine/engine_three_utils.ts

@@ -1,31 +1,7 @@
 import * as THREE from "three";
 import { Mathf } from "./engine_math"
 import { Vector3, Quaternion, Uniform } from "three";
-
-class CircularBuffer<T> {
-    private _factory: () => T;
-    private _cache: T[] = [];
-    private _maxSize: number;
-    private _index: number = 0;
-
-    constructor(factory: () => T, maxSize: number) {
-        this._factory = factory;
-        this._maxSize = maxSize;
-    }
-
-    get(): T {
-        let i = this._index++;
-        if (i >= this._cache.length) {
-            if (i >= this._maxSize) {
-                i = this._index = 0;
-            }
-            else {
-                this._cache.push(this._factory());
-            }
-        }
-        return this._cache[i];
-    }
-}
+import { CircularBuffer } from "./engine_utils";
 
 
 
@@ -39,10 +15,6 @@ export function lookAtInverse(obj: THREE.Object3D, target: Vector3) {
 
 const _worldPositions = new CircularBuffer(() => new THREE.Vector3(), 100);
 
-
-
-
-
 export function getWorldPosition(obj: THREE.Object3D, vec: THREE.Vector3 | null = null, updateParents: boolean = true): THREE.Vector3 {
     const wp = vec ?? _worldPositions.get();
     if (!obj) return wp.set(0, 0, 0);

package/src/engine/engine_types.ts

@@ -1,6 +1,8 @@
 import { Camera, Color, Material, Object3D, Vector3, Quaternion } from "three";
 import { RGBAColor } from "../engine-components/js-extensions/RGBAColor";
 import { CollisionDetectionMode, RigidbodyConstraints } from "./engine_physics.types";
+import { getWorldPosition } from "./engine_three_utils";
+import { CircularBuffer } from "./engine_utils";
 
 /** used to find data registered via gltf files e.g. find lightmaps for a Renderer component that were shipped inside a gltf */
 export declare type SourceIdentifier = string;
@@ -40,7 +42,7 @@ export interface IComponent {
     get name(): string;
     get layer(): number;
     get destroyed(): boolean;
-    get tag() : string;
+    get tag(): string;
 
     context: any;
 
@@ -84,7 +86,7 @@ export interface IComponent {
 
 
 export declare interface ICamera extends IComponent {
-    get isCamera() : boolean;
+    get isCamera(): boolean;
     applyClearFlagsIfIsActiveCamera(): unknown;
     buildCamera();
     get cam(): Camera;
@@ -147,34 +149,51 @@ export declare type ICollisionContext = {
 }
 
 
+export type Vec2 = {
+    x: number,
+    y: number
+}
+
 export type Vec3 = {
     x: number,
     y: number,
     z: number
 }
 
-export type Vec2 = {
-    x: number,
-    y: number
-}
+const contactsVectorBuffer = new CircularBuffer(() => new Vector3(), 20);
 
 export class ContactPoint {
 
-    readonly localPoint: Vec3;
+    private readonly _point: Vec3;
+    private readonly _normal: Vec3;
+
     readonly distance: number;
-    readonly normal: Vec3;
+    readonly impulse: number;
+    readonly friction: number;
 
-    constructor(localPt: Vec3, dist: number, normal: Vec3) {
-        this.localPoint = localPt;
-        this.distance = dist;
-        this.normal = normal;
+    /** worldspace point */
+    get point() {
+        const target = contactsVectorBuffer.get();
+        return target.set(this._point.x, this._point.y, this._point.z);
+    }
+
+    /** worldspace normal */
+    get normal() {
+        const target = contactsVectorBuffer.get();
+        return target.set(this._normal.x, this._normal.y, this._normal.z);
     }
 
+    constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number) {
+        this._point = point;
+        this.distance = dist;
+        this._normal = normal;
+        this.impulse = impulse;
+        this.friction = friction;
+    }
 }
 
 /// all info in here must be readonly because the object is only created once per started collision
 export class Collision {
-
     readonly contacts: ContactPoint[];
 
     constructor(obj: Object3D, otherCollider: ICollider, contacts: ContactPoint[]) {
@@ -203,7 +222,7 @@ export class Collision {
         return this.collider?.attachedRigidbody;
     }
 
-    
+
 
     // private _normal?: Vector3;
     // get normal(): Vector3 {

package/src/engine/engine_utils.ts

@@ -14,6 +14,33 @@ export function isDebugMode(): boolean {
 
 
 
+export class CircularBuffer<T> {
+    private _factory: () => T;
+    private _cache: T[] = [];
+    private _maxSize: number;
+    private _index: number = 0;
+
+    constructor(factory: () => T, maxSize: number) {
+        this._factory = factory;
+        this._maxSize = maxSize;
+    }
+
+    get(): T {
+        let i = this._index++;
+        if (i >= this._cache.length) {
+            if (i >= this._maxSize) {
+                i = this._index = 0;
+            }
+            else {
+                this._cache.push(this._factory());
+            }
+        }
+        return this._cache[i];
+    }
+}
+
+
+
 let saveParams: boolean = false;
 const requestedParams: Array<string> = [];
 setTimeout(() => {

package/src/engine/extensions/NEEDLE_lightmaps.ts

@@ -51,7 +51,7 @@ export class NEEDLE_lightmaps implements GLTFLoaderPlugin {
             const ext: LightmapExtension = extensions[EXTENSION_NAME];
             if (ext) {
                 const arr = ext.textures;
-                if (!arr.length) {
+                if (!arr?.length) {
                     return null;
                 }
                 if (debug)

package/src/engine-components/Component.ts

@@ -309,14 +309,17 @@ class Component implements IComponent, EventTarget {
     /** called on a component with a map of old to new guids (e.g. when instantiate generated new guids and e.g. timeline track bindings needs to remape them) */
     resolveGuids?(guidsMap: GuidsMap): void;
 
-    // TODO: can we not have these and then check in update loop if they are implemented (magick methods) ?
+    /** called once when the component becomes active for the first time */
     awake() { }
-    // update() { }
+    /** called every time when the component gets enabled (this is invoked after awake and before start) */
     onEnable() { }
     onDisable() { }
     onDestroy() {
         this.__destroyed = true;
     }
+    /** called when you decorate fields with the @validate() decorator
+     * @param field the name of the field that was changed
+     */
     onValidate?(prop?: string): void;
     start?(): void;
     earlyUpdate?(): void;
@@ -350,20 +353,35 @@ class Component implements IComponent, EventTarget {
         this.__internalDestroy();
     }
 
+    
+    
+    /** @internal */
     protected __didAwake: boolean = false;
+    
+    /** @internal */
     private __didStart: boolean = false;
+    
+    /** @internal */
     protected __didEnable: boolean = false;
+    
+    /** @internal */
     protected __isEnabled: boolean | undefined = undefined;
+    
+    /** @internal */
     private __destroyed: boolean = false;
-
+    
+    /** @internal */
     get __internalDidAwakeAndStart() { return this.__didAwake && this.__didStart; }
 
-
+    
+    /** @internal */
     constructor() {
         // super();
         this.__internalNewInstanceCreated();
     }
 
+    
+    /** @internal */
     __internalNewInstanceCreated() {
         this.__didAwake = false;
         this.__didStart = false;
@@ -373,6 +391,8 @@ class Component implements IComponent, EventTarget {
         // this.__internalResetsCachedPhysicsData();
     }
 
+    
+    /** @internal */
     __internalAwake() {
         if (this.__didAwake) return;
         // console.log("__internalAwake");
@@ -382,12 +402,16 @@ class Component implements IComponent, EventTarget {
         this.awake();
     }
 
+    
+    /** @internal */
     __internalStart() {
         if (this.__didStart) return;
         this.__didStart = true;
         if (this.start) this.start();
     }
 
+    
+    /** @internal */
     __internalEnable(): boolean {
         if (this.__didEnable) return false;
         // console.trace("INTERNAL ENABLE");
@@ -398,6 +422,7 @@ class Component implements IComponent, EventTarget {
         return true;
     }
 
+    /** @internal */
     __internalDisable() {
         if (!this.__didEnable) return;
         this.__didEnable = false;
@@ -408,6 +433,7 @@ class Component implements IComponent, EventTarget {
         this.__isEnabled = false;
     }
 
+    /** @internal */
     __internalDestroy() {
         if (this.__destroyed) return;
         this.__destroyed = true;

package/src/engine-components/Joints.ts

@@ -13,9 +13,6 @@ export abstract class Joint extends Behaviour {
     private _rigidBody: Rigidbody | null = null;
 
 
-    @serializeable(Vector3)
-    connectedAnchor?: Vector3;
-
     onEnable() {
         if (!this._rigidBody) this._rigidBody = this.gameObject.getComponent(Rigidbody);
         if (this.rigidBody && this.connectedBody)
@@ -24,8 +21,9 @@ export abstract class Joint extends Behaviour {
 
     private *create() {
         yield;
-        if (this.rigidBody && this.connectedBody)
-            this.createJoint(this.rigidBody, this.connectedBody);
+        if (this.rigidBody && this.connectedBody) {
+            this.createJoint(this.rigidBody, this.connectedBody)
+        }
     }
 
     protected abstract createJoint(self: Rigidbody, other: Rigidbody);
@@ -34,7 +32,21 @@ export abstract class Joint extends Behaviour {
 export class FixedJoint extends Joint {
 
     protected createJoint(self: Rigidbody, other: Rigidbody) {
-        if (this.connectedAnchor)
-            this.context.physics.addFixedJoint(self, other, this.connectedAnchor);
+        this.context.physics.addFixedJoint(self, other);
     }
+}
+
+export class HingeJoint extends Joint {
+
+    @serializeable(Vector3)
+    anchor?: Vector3;
+
+    @serializeable(Vector3)
+    axis?: Vector3;
+
+    protected createJoint(self: Rigidbody, other: Rigidbody) {
+        if (this.axis && this.anchor)
+            this.context.physics.addHingeJoint(self, other, this.anchor, this.axis);
+    }
+
 }

package/src/engine-components/codegen/components.ts

@@ -39,6 +39,7 @@ export { GroundProjectedEnv } from "../GroundProjection";
 export { Interactable } from "../Interactable";
 export { UsageMarker } from "../Interactable";
 export { FixedJoint } from "../Joints";
+export { HingeJoint } from "../Joints";
 export { Light } from "../Light";
 export { LODModel } from "../LODGroup";
 export { LODGroup } from "../LODGroup";