@needle-tools/engine 3.28.6-beta → 3.28.7-beta.1

package/src/engine-components/RigidBody.ts

@@ -1,454 +1,454 @@
-import { Behaviour } from "./Component.js";
-import * as THREE from 'three'
-import { getWorldPosition } from "../engine/engine_three_utils.js";
-import { serializable } from "../engine/engine_serialization_decorator.js";
-import { Watch } from "../engine/engine_utils.js";
-import { Matrix4, Object3D, Vector3 } from "three";
-import type { IRigidbody, Vec3 } from "../engine/engine_types.js";
-import { CollisionDetectionMode, RigidbodyConstraints } from "../engine/engine_physics.types.js";
-import { validate } from "../engine/engine_util_decorator.js";
-import { Context, FrameEvent } from "../engine/engine_setup.js";
-
-class TransformWatch {
-
-    get isDirty(): boolean {
-        return this.positionChanged || this.rotationChanged;
-    }
-    positionChanged: boolean = false;
-    rotationChanged: boolean = false;
-
-    position?: { x?: number, y?: number, z?: number };
-    quaternion?: { _x?: number, _y?: number, _z?: number, _w?: number };
-
-    private _positionKeys: string[] = ["x", "y", "z"];
-    private _quaternionKeys: string[] = ["_x", "_y", "_z", "_w"];
-
-    reset(clearPreviousValues: boolean = false) {
-        this.positionChanged = false;
-        this.rotationChanged = false;
-        this.mute = false;
-
-        if (clearPreviousValues) {
-            if (this.position)
-                for (const key of this._positionKeys)
-                    delete this.position[key];
-            if (this.quaternion)
-                for (const key of this._quaternionKeys)
-                    delete this.quaternion[key];
-        }
-    }
-
-    syncValues() {
-        for (const key of this._positionKeys) {
-            this.position![key] = this.obj.position[key];
-        }
-        for (const key of this._quaternionKeys) {
-            this.quaternion![key] = this.obj.quaternion[key];
-        }
-    }
-
-    mute: boolean = false;
-
-    applyValues() {
-        // only apply the values that actually changed
-        // since we want to still control all the other values via physics 
-        if (this.positionChanged && this.position) {
-            for (const key of this._positionKeys) {
-                const val = this.position[key];
-                if (val !== undefined)
-                    this.obj.position[key] = val;
-            }
-        }
-        if (this.rotationChanged) {
-            if (this.quaternion) {
-                for (const key of this._quaternionKeys) {
-                    const val = this.quaternion[key];
-                    if (val !== undefined)
-                        this.obj.quaternion[key] = val;
-                }
-            }
-        }
-    }
-
-    readonly context: Context;
-    readonly obj: Object3D;
-    private _positionWatch?: Watch;
-    private _rotationWatch?: Watch;
-
-    constructor(obj: Object3D, context: Context) {
-        this.context = context;
-        this.obj = obj;
-    }
-
-    start(position: boolean, rotation: boolean) {
-        this.reset();
-        if (position) {
-            if (!this._positionWatch)
-                this._positionWatch = new Watch(this.obj.position, ["x", "y", "z"]);
-            this._positionWatch.apply();
-            this.position = {};
-            // this.position = this.obj.position.clone();
-            this._positionWatch.subscribeWrite((val, prop) => {
-                if (this.context.physics.engine?.isUpdating || this.mute) return;
-                const prev = this.position![prop];
-                if (Math.abs(prev - val) < .00001) return;
-                this.position![prop] = val;
-                this.positionChanged = true;
-            })
-        }
-        if (rotation) {
-            if (!this._rotationWatch)
-                this._rotationWatch = new Watch(this.obj.quaternion, ["_x", "_y", "_z", "_w"]);
-            this._rotationWatch.apply();
-            this.quaternion = {};
-            // this.quaternion = this.obj.quaternion.clone();
-            this._rotationWatch.subscribeWrite((val, prop) => {
-                if (this.context.physics.engine?.isUpdating || this.mute) return;
-                const prev = this.quaternion![prop];
-                if (Math.abs(prev - val) < .00001) return;
-                this.quaternion![prop] = val;
-                this.rotationChanged = true;
-            })
-        }
-
-        // detect changes in the parent matrix
-        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;
-                lastParentMatrix.copy(parent);
-            }
-            return original(parent, matrix);;
-        }
-    }
-
-    stop() {
-        this._positionWatch?.revoke();
-        this._rotationWatch?.revoke();
-    }
-}
-
-
-export class Rigidbody extends Behaviour implements IRigidbody {
-
-    /** When true the mass will be automatically calculated by the attached colliders */
-    @validate()
-    autoMass: boolean = true;
-
-    /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes  
-     * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
-     */
-    @serializable()
-    set mass(value: number) {
-        if (value === this._mass) return;
-        this._mass = value;
-        this._propertiesChanged = true;
-        // When setting the mass manually we disable autoMass
-        if (this.__didAwake) {
-            this.autoMass = false;
-        }
-    }
-    get mass() {
-        if (this.autoMass)
-            return this.context.physics.engine?.getBody(this)?.mass() ?? -1;
-        return this._mass;
-    }
-    private _mass: number = 0;
-
-    @validate()
-    @serializable()
-    useGravity: boolean = true;
-
-    @validate()
-    @serializable()
-    constraints: RigidbodyConstraints = RigidbodyConstraints.None;
-
-    @validate()
-    @serializable()
-    isKinematic: boolean = false;
-
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#damping */
-    @validate()
-    @serializable()
-    drag: number = 0;
-
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#damping */
-    @validate()
-    @serializable()
-    angularDrag: number = 1;
-
-    @validate()
-    @serializable()
-    detectCollisions: boolean = true;
-
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#sleeping */
-    @validate()
-    @serializable()
-    sleepThreshold: number = 0.01;
-
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#continuous-collision-detection */
-    @validate()
-    @serializable()
-    collisionDetectionMode: CollisionDetectionMode = CollisionDetectionMode.Discrete;
-
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    get lockPositionX() {
-        return (this.constraints & RigidbodyConstraints.FreezePositionX) !== 0;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    get lockPositionY() {
-        return (this.constraints & RigidbodyConstraints.FreezePositionY) !== 0;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    get lockPositionZ() {
-        return (this.constraints & RigidbodyConstraints.FreezePositionZ) !== 0;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    get lockRotationX() {
-        return (this.constraints & RigidbodyConstraints.FreezeRotationX) !== 0;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    get lockRotationY() {
-        return (this.constraints & RigidbodyConstraints.FreezeRotationY) !== 0;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    get lockRotationZ() {
-        return (this.constraints & RigidbodyConstraints.FreezeRotationZ) !== 0;
-    }
-
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    set lockPositionX(v: boolean) {
-        if (v) this.constraints |= RigidbodyConstraints.FreezePositionX;
-        else this.constraints &= ~RigidbodyConstraints.FreezePositionX;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    set lockPositionY(v: boolean) {
-        if (v) this.constraints |= RigidbodyConstraints.FreezePositionY;
-        else this.constraints &= ~RigidbodyConstraints.FreezePositionY;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    set lockPositionZ(v: boolean) {
-        if (v) this.constraints |= RigidbodyConstraints.FreezePositionZ;
-        else this.constraints &= ~RigidbodyConstraints.FreezePositionZ;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    set lockRotationX(v: boolean) {
-        if (v) this.constraints |= RigidbodyConstraints.FreezeRotationX;
-        else this.constraints &= ~RigidbodyConstraints.FreezeRotationX;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    set lockRotationY(v: boolean) {
-        if (v) this.constraints |= RigidbodyConstraints.FreezeRotationY;
-        else this.constraints &= ~RigidbodyConstraints.FreezeRotationY;
-    }
-    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
-    set lockRotationZ(v: boolean) {
-        if (v) this.constraints |= RigidbodyConstraints.FreezeRotationZ;
-        else this.constraints &= ~RigidbodyConstraints.FreezeRotationZ;
-    }
-
-    /** Gravity is such a common force that it is implemented as a special case (even if it could easily be implemented by the user using force application). Note however that a change of gravity won't automatically wake-up the sleeping bodies so keep in mind that you may want to wake them up manually before a gravity change.   
-     * 
-     * It is possible to change the way gravity affects a specific rigid-body by setting the rigid-body's gravity scale to a value other than 1.0. The magnitude of the gravity applied to this body will be multiplied by this scaling factor. Therefore, a gravity scale set to 0.0 will disable gravity for the rigid-body whereas a gravity scale set to 2.0 will make it twice as strong. A negative value will flip the direction of the gravity for this rigid-body.
-     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#gravity
-     */
-    set gravityScale(val: number) {
-        this._gravityScale = val;
-    }
-    get gravityScale() {
-        return this._gravityScale;
-    }
-    @validate()
-    private _gravityScale: number = 1;
-
-    /** Rigidbodies with higher dominance will be immune to forces originating from contacts with rigidbodies of lower dominance.  
-     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#dominance
-     */
-    @validate()
-    dominanceGroup : number = 0;
-
-    private static tempPosition: THREE.Vector3 = new THREE.Vector3();
-    private _propertiesChanged: boolean = false;
-    private _currentVelocity: THREE.Vector3 = new THREE.Vector3();
-    private _smoothedVelocity: THREE.Vector3 = new THREE.Vector3();
-    private _smoothedVelocityGetter: THREE.Vector3 = new THREE.Vector3();
-    private _lastPosition: THREE.Vector3 = new THREE.Vector3();
-
-    private _watch?: TransformWatch;
-
-    awake() {
-        this._watch = undefined;
-        this._propertiesChanged = false;
-    }
-
-    onEnable() {
-        if (!this._watch) {
-            this._watch = new TransformWatch(this.gameObject, this.context);
-        }
-        this._watch.start(true, true);
-        this.startCoroutine(this.beforePhysics(), FrameEvent.LateUpdate);
-    }
-
-    onDisable() {
-        this._watch?.stop();
-        this.context.physics.engine?.removeBody(this);
-    }
-
-    onDestroy(): void {
-        this.context.physics.engine?.removeBody(this);
-    }
-
-    onValidate() {
-        this._propertiesChanged = true;
-    }
-
-    // need to do this right before updating physics to prevent rendered object glitching through physical bodies
-    *beforePhysics() {
-        while (true) {
-            if (this._propertiesChanged) {
-                this._propertiesChanged = false;
-                this.context.physics.engine?.updateProperties(this);
-            }
-            if (this._watch?.isDirty) {
-                this._watch.mute = true;
-                this._watch.applyValues();
-                this.context.physics.engine?.updateBody(this, this._watch.positionChanged, this._watch.rotationChanged);
-                this._watch.reset();
-            }
-            else this._watch?.syncValues();
-            this.captureVelocity();
-            yield;
-        }
-    }
-
-    /** Will reset forces before setting the object world position */
-    public teleport(pt: { x: number, y: number, z: number }, localspace: boolean = true) {
-        this._watch?.reset(true);
-        if (localspace) this.gameObject.position.set(pt.x, pt.y, pt.z);
-        else this.setWorldPosition(pt.x, pt.y, pt.z);
-        this.resetForcesAndTorques();
-        this.resetVelocities();
-    }
-
-    public resetForces(wakeup:boolean = true) {
-        this.context.physics.engine?.resetForces(this, wakeup);
-    }
-
-    public resetTorques(wakeup:boolean = true) {
-        this.context.physics.engine?.resetTorques(this, wakeup);
-    }
-
-    public resetVelocities() {
-        this.setVelocity(0, 0, 0);
-        this.setAngularVelocity(0, 0, 0);
-    }
-
-    public resetForcesAndTorques() {
-        this.resetForces();
-        this.resetTorques();
-    }
-
-    /** When a dynamic rigid-body doesn't move (or moves very slowly) during a few seconds, it will be marked as sleeping by the physics pipeline. Rigid-bodies marked as sleeping are no longer simulated by the physics engine until they are woken up. That way the physics engine doesn't waste any computational resources simulating objects that don't actually move. They are woken up automatically whenever another non-sleeping rigid-body starts interacting with them (either with a joint, or with one of its attached colliders generating contacts).  
-     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#sleeping */
-    public wakeUp() {
-        this.context.physics.engine?.wakeup(this);
-    }
-
-    /** Forces affect the rigid-body's acceleration whereas impulses affect the rigid-body's velocity 
-     * the acceleration change is equal to the force divided by the mass:
-     * @link see https://rapier.rs/docs/user_guides/javascript/rigid_bodies#forces-and-impulses */
-    public applyForce(vec: Vector3 | Vec3, _rel?: THREE.Vector3, wakeup: boolean = true) {
-        this.context.physics.engine?.addForce(this, vec, wakeup);
-    }
-
-    /** Forces affect the rigid-body's acceleration whereas impulses affect the rigid-body's velocity 
-     * the velocity change is equal to the impulse divided by the mass  
-     * @link see https://rapier.rs/docs/user_guides/javascript/rigid_bodies#forces-and-impulses */
-    public applyImpulse(vec: Vector3 | Vec3, wakeup: boolean = true) {
-        this.context.physics.engine?.applyImpulse(this, vec, wakeup);
-    }
-
-    /** @link see https://rapier.rs/docs/user_guides/javascript/rigid_bodies#forces-and-impulses */
-    public setForce(x: Vector3 | Vec3 | number, y?: number, z?: number, wakeup: boolean = true) {
-        this.context.physics.engine?.resetForces(this, wakeup);
-        if (typeof x === "number") {
-            y ??= 0;
-            z ??= 0;
-            this.context.physics.engine?.addForce(this, { x, y, z }, wakeup);
-        }
-        else {
-            this.context.physics.engine?.addForce(this, x, wakeup);
-        }
-    }
-
-    /** The velocity of a dynamic rigid-body controls how fast it is moving in time. The velocity is applied at the center-of-mass of the rigid-body. This method returns the current linear velocity of the rigid-body. 
-     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#velocity */
-    public getVelocity(): Vector3 {
-        const vel = this.context.physics.engine?.getLinearVelocity(this);
-        if (!vel) return this._currentVelocity.set(0, 0, 0);
-        this._currentVelocity.x = vel.x;
-        this._currentVelocity.y = vel.y;
-        this._currentVelocity.z = vel.z;
-        return this._currentVelocity;
-    }
-
-    public setVelocity(x: number | Vector3, y?: number, z?: number, wakeup: boolean = true) {
-        if (x instanceof Vector3) {
-            const vec = x;
-            this.context.physics.engine?.setLinearVelocity(this, vec, wakeup);
-            return;
-        }
-        if (y === undefined || z === undefined) return;
-        this.context.physics.engine?.setLinearVelocity(this, { x: x, y: y, z: z }, wakeup);
-    }
-
-    /** The velocity of a dynamic rigid-body controls how fast it is moving in time. The velocity is applied at the center-of-mass of the rigid-body. This method returns the current angular velocity of the rigid-body. 
-     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#velocity */
-    public getAngularVelocity(): Vector3 {
-        const vel = this.context.physics.engine?.getAngularVelocity(this);
-        if (!vel) return this._currentVelocity.set(0, 0, 0);
-        this._currentVelocity.x = vel.x;
-        this._currentVelocity.y = vel.y;
-        this._currentVelocity.z = vel.z;
-        return this._currentVelocity;
-    }
-
-    public setAngularVelocity(x: number | Vector3, y?: number, z?: number, wakeup: boolean = true) {
-        if (x instanceof Vector3) {
-            const vec = x;
-            this.context.physics.engine?.setAngularVelocity(this, vec, wakeup);
-            return;
-        }
-        if (y === undefined || z === undefined) return;
-        this.context.physics.engine?.setAngularVelocity(this, { x: x, y: y, z: z }, wakeup);
-    }
-
-    /** Set the angular velocity of a rigidbody (equivalent to calling `setAngularVelocity`) */
-    public setTorque(x: number | Vector3, y: number, z: number) {
-        this.setAngularVelocity(x, y, z);
-    }
-
-    /** Returns the rigidbody velocity smoothed over ~ 10 frames */
-    public get smoothedVelocity(): Vector3 {
-        this._smoothedVelocityGetter.copy(this._smoothedVelocity);
-        return this._smoothedVelocityGetter.multiplyScalar(1 / this.context.time.deltaTime);
-    }
-
-
-    /**d
-     * @deprecated not used anymore and will be removed in a future update
-     */
-    public setBodyFromGameObject(_velocity: THREE.Vector3 | null | { x: number, y: number, z: number } = null) { }
-
-
-    private captureVelocity() {
-        const wp = getWorldPosition(this.gameObject);
-        Rigidbody.tempPosition.copy(wp);
-        const vel = wp.sub(this._lastPosition);
-        this._lastPosition.copy(Rigidbody.tempPosition);
-        this._smoothedVelocity.lerp(vel, this.context.time.deltaTime / .1);
-    }
+import { Behaviour } from "./Component.js";
+import * as THREE from 'three'
+import { getWorldPosition } from "../engine/engine_three_utils.js";
+import { serializable } from "../engine/engine_serialization_decorator.js";
+import { Watch } from "../engine/engine_utils.js";
+import { Matrix4, Object3D, Vector3 } from "three";
+import type { IRigidbody, Vec3 } from "../engine/engine_types.js";
+import { CollisionDetectionMode, RigidbodyConstraints } from "../engine/engine_physics.types.js";
+import { validate } from "../engine/engine_util_decorator.js";
+import { Context, FrameEvent } from "../engine/engine_setup.js";
+
+class TransformWatch {
+
+    get isDirty(): boolean {
+        return this.positionChanged || this.rotationChanged;
+    }
+    positionChanged: boolean = false;
+    rotationChanged: boolean = false;
+
+    position?: { x?: number, y?: number, z?: number };
+    quaternion?: { _x?: number, _y?: number, _z?: number, _w?: number };
+
+    private _positionKeys: string[] = ["x", "y", "z"];
+    private _quaternionKeys: string[] = ["_x", "_y", "_z", "_w"];
+
+    reset(clearPreviousValues: boolean = false) {
+        this.positionChanged = false;
+        this.rotationChanged = false;
+        this.mute = false;
+
+        if (clearPreviousValues) {
+            if (this.position)
+                for (const key of this._positionKeys)
+                    delete this.position[key];
+            if (this.quaternion)
+                for (const key of this._quaternionKeys)
+                    delete this.quaternion[key];
+        }
+    }
+
+    syncValues() {
+        for (const key of this._positionKeys) {
+            this.position![key] = this.obj.position[key];
+        }
+        for (const key of this._quaternionKeys) {
+            this.quaternion![key] = this.obj.quaternion[key];
+        }
+    }
+
+    mute: boolean = false;
+
+    applyValues() {
+        // only apply the values that actually changed
+        // since we want to still control all the other values via physics 
+        if (this.positionChanged && this.position) {
+            for (const key of this._positionKeys) {
+                const val = this.position[key];
+                if (val !== undefined)
+                    this.obj.position[key] = val;
+            }
+        }
+        if (this.rotationChanged) {
+            if (this.quaternion) {
+                for (const key of this._quaternionKeys) {
+                    const val = this.quaternion[key];
+                    if (val !== undefined)
+                        this.obj.quaternion[key] = val;
+                }
+            }
+        }
+    }
+
+    readonly context: Context;
+    readonly obj: Object3D;
+    private _positionWatch?: Watch;
+    private _rotationWatch?: Watch;
+
+    constructor(obj: Object3D, context: Context) {
+        this.context = context;
+        this.obj = obj;
+    }
+
+    start(position: boolean, rotation: boolean) {
+        this.reset();
+        if (position) {
+            if (!this._positionWatch)
+                this._positionWatch = new Watch(this.obj.position, ["x", "y", "z"]);
+            this._positionWatch.apply();
+            this.position = {};
+            // this.position = this.obj.position.clone();
+            this._positionWatch.subscribeWrite((val, prop) => {
+                if (this.context.physics.engine?.isUpdating || this.mute) return;
+                const prev = this.position![prop];
+                if (Math.abs(prev - val) < .00001) return;
+                this.position![prop] = val;
+                this.positionChanged = true;
+            })
+        }
+        if (rotation) {
+            if (!this._rotationWatch)
+                this._rotationWatch = new Watch(this.obj.quaternion, ["_x", "_y", "_z", "_w"]);
+            this._rotationWatch.apply();
+            this.quaternion = {};
+            // this.quaternion = this.obj.quaternion.clone();
+            this._rotationWatch.subscribeWrite((val, prop) => {
+                if (this.context.physics.engine?.isUpdating || this.mute) return;
+                const prev = this.quaternion![prop];
+                if (Math.abs(prev - val) < .00001) return;
+                this.quaternion![prop] = val;
+                this.rotationChanged = true;
+            })
+        }
+
+        // detect changes in the parent matrix
+        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;
+                lastParentMatrix.copy(parent);
+            }
+            return original(parent, matrix);;
+        }
+    }
+
+    stop() {
+        this._positionWatch?.revoke();
+        this._rotationWatch?.revoke();
+    }
+}
+
+
+export class Rigidbody extends Behaviour implements IRigidbody {
+
+    /** When true the mass will be automatically calculated by the attached colliders */
+    @validate()
+    autoMass: boolean = true;
+
+    /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes  
+     * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
+     */
+    @serializable()
+    set mass(value: number) {
+        if (value === this._mass) return;
+        this._mass = value;
+        this._propertiesChanged = true;
+        // When setting the mass manually we disable autoMass
+        if (this.__didAwake) {
+            this.autoMass = false;
+        }
+    }
+    get mass() {
+        if (this.autoMass)
+            return this.context.physics.engine?.getBody(this)?.mass() ?? -1;
+        return this._mass;
+    }
+    private _mass: number = 0;
+
+    @validate()
+    @serializable()
+    useGravity: boolean = true;
+
+    @validate()
+    @serializable()
+    constraints: RigidbodyConstraints = RigidbodyConstraints.None;
+
+    @validate()
+    @serializable()
+    isKinematic: boolean = false;
+
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#damping */
+    @validate()
+    @serializable()
+    drag: number = 0;
+
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#damping */
+    @validate()
+    @serializable()
+    angularDrag: number = 1;
+
+    @validate()
+    @serializable()
+    detectCollisions: boolean = true;
+
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#sleeping */
+    @validate()
+    @serializable()
+    sleepThreshold: number = 0.01;
+
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#continuous-collision-detection */
+    @validate()
+    @serializable()
+    collisionDetectionMode: CollisionDetectionMode = CollisionDetectionMode.Discrete;
+
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    get lockPositionX() {
+        return (this.constraints & RigidbodyConstraints.FreezePositionX) !== 0;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    get lockPositionY() {
+        return (this.constraints & RigidbodyConstraints.FreezePositionY) !== 0;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    get lockPositionZ() {
+        return (this.constraints & RigidbodyConstraints.FreezePositionZ) !== 0;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    get lockRotationX() {
+        return (this.constraints & RigidbodyConstraints.FreezeRotationX) !== 0;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    get lockRotationY() {
+        return (this.constraints & RigidbodyConstraints.FreezeRotationY) !== 0;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    get lockRotationZ() {
+        return (this.constraints & RigidbodyConstraints.FreezeRotationZ) !== 0;
+    }
+
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    set lockPositionX(v: boolean) {
+        if (v) this.constraints |= RigidbodyConstraints.FreezePositionX;
+        else this.constraints &= ~RigidbodyConstraints.FreezePositionX;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    set lockPositionY(v: boolean) {
+        if (v) this.constraints |= RigidbodyConstraints.FreezePositionY;
+        else this.constraints &= ~RigidbodyConstraints.FreezePositionY;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    set lockPositionZ(v: boolean) {
+        if (v) this.constraints |= RigidbodyConstraints.FreezePositionZ;
+        else this.constraints &= ~RigidbodyConstraints.FreezePositionZ;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    set lockRotationX(v: boolean) {
+        if (v) this.constraints |= RigidbodyConstraints.FreezeRotationX;
+        else this.constraints &= ~RigidbodyConstraints.FreezeRotationX;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    set lockRotationY(v: boolean) {
+        if (v) this.constraints |= RigidbodyConstraints.FreezeRotationY;
+        else this.constraints &= ~RigidbodyConstraints.FreezeRotationY;
+    }
+    /** @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#locking-translationsrotations */
+    set lockRotationZ(v: boolean) {
+        if (v) this.constraints |= RigidbodyConstraints.FreezeRotationZ;
+        else this.constraints &= ~RigidbodyConstraints.FreezeRotationZ;
+    }
+
+    /** Gravity is such a common force that it is implemented as a special case (even if it could easily be implemented by the user using force application). Note however that a change of gravity won't automatically wake-up the sleeping bodies so keep in mind that you may want to wake them up manually before a gravity change.   
+     * 
+     * It is possible to change the way gravity affects a specific rigid-body by setting the rigid-body's gravity scale to a value other than 1.0. The magnitude of the gravity applied to this body will be multiplied by this scaling factor. Therefore, a gravity scale set to 0.0 will disable gravity for the rigid-body whereas a gravity scale set to 2.0 will make it twice as strong. A negative value will flip the direction of the gravity for this rigid-body.
+     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#gravity
+     */
+    set gravityScale(val: number) {
+        this._gravityScale = val;
+    }
+    get gravityScale() {
+        return this._gravityScale;
+    }
+    @validate()
+    private _gravityScale: number = 1;
+
+    /** Rigidbodies with higher dominance will be immune to forces originating from contacts with rigidbodies of lower dominance.  
+     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#dominance
+     */
+    @validate()
+    dominanceGroup : number = 0;
+
+    private static tempPosition: THREE.Vector3 = new THREE.Vector3();
+    private _propertiesChanged: boolean = false;
+    private _currentVelocity: THREE.Vector3 = new THREE.Vector3();
+    private _smoothedVelocity: THREE.Vector3 = new THREE.Vector3();
+    private _smoothedVelocityGetter: THREE.Vector3 = new THREE.Vector3();
+    private _lastPosition: THREE.Vector3 = new THREE.Vector3();
+
+    private _watch?: TransformWatch;
+
+    awake() {
+        this._watch = undefined;
+        this._propertiesChanged = false;
+    }
+
+    onEnable() {
+        if (!this._watch) {
+            this._watch = new TransformWatch(this.gameObject, this.context);
+        }
+        this._watch.start(true, true);
+        this.startCoroutine(this.beforePhysics(), FrameEvent.LateUpdate);
+    }
+
+    onDisable() {
+        this._watch?.stop();
+        this.context.physics.engine?.removeBody(this);
+    }
+
+    onDestroy(): void {
+        this.context.physics.engine?.removeBody(this);
+    }
+
+    onValidate() {
+        this._propertiesChanged = true;
+    }
+
+    // need to do this right before updating physics to prevent rendered object glitching through physical bodies
+    *beforePhysics() {
+        while (true) {
+            if (this._propertiesChanged) {
+                this._propertiesChanged = false;
+                this.context.physics.engine?.updateProperties(this);
+            }
+            if (this._watch?.isDirty) {
+                this._watch.mute = true;
+                this._watch.applyValues();
+                this.context.physics.engine?.updateBody(this, this._watch.positionChanged, this._watch.rotationChanged);
+                this._watch.reset();
+            }
+            else this._watch?.syncValues();
+            this.captureVelocity();
+            yield;
+        }
+    }
+
+    /** Will reset forces before setting the object world position */
+    public teleport(pt: { x: number, y: number, z: number }, localspace: boolean = true) {
+        this._watch?.reset(true);
+        if (localspace) this.gameObject.position.set(pt.x, pt.y, pt.z);
+        else this.setWorldPosition(pt.x, pt.y, pt.z);
+        this.resetForcesAndTorques();
+        this.resetVelocities();
+    }
+
+    public resetForces(wakeup:boolean = true) {
+        this.context.physics.engine?.resetForces(this, wakeup);
+    }
+
+    public resetTorques(wakeup:boolean = true) {
+        this.context.physics.engine?.resetTorques(this, wakeup);
+    }
+
+    public resetVelocities() {
+        this.setVelocity(0, 0, 0);
+        this.setAngularVelocity(0, 0, 0);
+    }
+
+    public resetForcesAndTorques() {
+        this.resetForces();
+        this.resetTorques();
+    }
+
+    /** When a dynamic rigid-body doesn't move (or moves very slowly) during a few seconds, it will be marked as sleeping by the physics pipeline. Rigid-bodies marked as sleeping are no longer simulated by the physics engine until they are woken up. That way the physics engine doesn't waste any computational resources simulating objects that don't actually move. They are woken up automatically whenever another non-sleeping rigid-body starts interacting with them (either with a joint, or with one of its attached colliders generating contacts).  
+     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#sleeping */
+    public wakeUp() {
+        this.context.physics.engine?.wakeup(this);
+    }
+
+    /** Forces affect the rigid-body's acceleration whereas impulses affect the rigid-body's velocity 
+     * the acceleration change is equal to the force divided by the mass:
+     * @link see https://rapier.rs/docs/user_guides/javascript/rigid_bodies#forces-and-impulses */
+    public applyForce(vec: Vector3 | Vec3, _rel?: THREE.Vector3, wakeup: boolean = true) {
+        this.context.physics.engine?.addForce(this, vec, wakeup);
+    }
+
+    /** Forces affect the rigid-body's acceleration whereas impulses affect the rigid-body's velocity 
+     * the velocity change is equal to the impulse divided by the mass  
+     * @link see https://rapier.rs/docs/user_guides/javascript/rigid_bodies#forces-and-impulses */
+    public applyImpulse(vec: Vector3 | Vec3, wakeup: boolean = true) {
+        this.context.physics.engine?.applyImpulse(this, vec, wakeup);
+    }
+
+    /** @link see https://rapier.rs/docs/user_guides/javascript/rigid_bodies#forces-and-impulses */
+    public setForce(x: Vector3 | Vec3 | number, y?: number, z?: number, wakeup: boolean = true) {
+        this.context.physics.engine?.resetForces(this, wakeup);
+        if (typeof x === "number") {
+            y ??= 0;
+            z ??= 0;
+            this.context.physics.engine?.addForce(this, { x, y, z }, wakeup);
+        }
+        else {
+            this.context.physics.engine?.addForce(this, x, wakeup);
+        }
+    }
+
+    /** The velocity of a dynamic rigid-body controls how fast it is moving in time. The velocity is applied at the center-of-mass of the rigid-body. This method returns the current linear velocity of the rigid-body. 
+     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#velocity */
+    public getVelocity(): Vector3 {
+        const vel = this.context.physics.engine?.getLinearVelocity(this);
+        if (!vel) return this._currentVelocity.set(0, 0, 0);
+        this._currentVelocity.x = vel.x;
+        this._currentVelocity.y = vel.y;
+        this._currentVelocity.z = vel.z;
+        return this._currentVelocity;
+    }
+
+    public setVelocity(x: number | Vector3, y?: number, z?: number, wakeup: boolean = true) {
+        if (x instanceof Vector3) {
+            const vec = x;
+            this.context.physics.engine?.setLinearVelocity(this, vec, wakeup);
+            return;
+        }
+        if (y === undefined || z === undefined) return;
+        this.context.physics.engine?.setLinearVelocity(this, { x: x, y: y, z: z }, wakeup);
+    }
+
+    /** The velocity of a dynamic rigid-body controls how fast it is moving in time. The velocity is applied at the center-of-mass of the rigid-body. This method returns the current angular velocity of the rigid-body. 
+     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#velocity */
+    public getAngularVelocity(): Vector3 {
+        const vel = this.context.physics.engine?.getAngularVelocity(this);
+        if (!vel) return this._currentVelocity.set(0, 0, 0);
+        this._currentVelocity.x = vel.x;
+        this._currentVelocity.y = vel.y;
+        this._currentVelocity.z = vel.z;
+        return this._currentVelocity;
+    }
+
+    public setAngularVelocity(x: number | Vector3, y?: number, z?: number, wakeup: boolean = true) {
+        if (x instanceof Vector3) {
+            const vec = x;
+            this.context.physics.engine?.setAngularVelocity(this, vec, wakeup);
+            return;
+        }
+        if (y === undefined || z === undefined) return;
+        this.context.physics.engine?.setAngularVelocity(this, { x: x, y: y, z: z }, wakeup);
+    }
+
+    /** Set the angular velocity of a rigidbody (equivalent to calling `setAngularVelocity`) */
+    public setTorque(x: number | Vector3, y: number, z: number) {
+        this.setAngularVelocity(x, y, z);
+    }
+
+    /** Returns the rigidbody velocity smoothed over ~ 10 frames */
+    public get smoothedVelocity(): Vector3 {
+        this._smoothedVelocityGetter.copy(this._smoothedVelocity);
+        return this._smoothedVelocityGetter.multiplyScalar(1 / this.context.time.deltaTime);
+    }
+
+
+    /**d
+     * @deprecated not used anymore and will be removed in a future update
+     */
+    public setBodyFromGameObject(_velocity: THREE.Vector3 | null | { x: number, y: number, z: number } = null) { }
+
+
+    private captureVelocity() {
+        const wp = getWorldPosition(this.gameObject);
+        Rigidbody.tempPosition.copy(wp);
+        const vel = wp.sub(this._lastPosition);
+        this._lastPosition.copy(Rigidbody.tempPosition);
+        this._smoothedVelocity.lerp(vel, this.context.time.deltaTime / .1);
+    }
 }