Needle Engine 3.27.3-beta

Files changed (9) hide show

src/engine-components/api.ts +2 -0
src/engine-components/Component.ts +8 -45
src/engine/engine_instancing.ts +21 -3
src/engine/engine_physics.ts +59 -20
src/engine-components/ui/Image.ts +1 -1
src/engine-components/ParticleSystem.ts +54 -17
src/engine/codegen/register_types.ts +2 -2
src/engine-components/Renderer.ts +39 -3
src/engine-components/RigidBody.ts +51 -15

src/engine-components/api.ts CHANGED Viewed

@@ -18,3 +18,5 @@
 import "./CameraUtils.js"
 import "./AnimationUtils.js"
+export { ParticleSystemBaseBehaviour, type QParticle, type QParticleBehaviour } from "./ParticleSystem.js"

src/engine-components/Component.ts CHANGED Viewed

@@ -572,23 +572,8 @@
         }
     }
-    // TODO move this to threeutils
-    // we need a copy for modifying the values to local space
-    private static _worldPositionBuffer: Vector3 = new Vector3();
-    private static _worldQuaternionBuffer: Quaternion = new Quaternion();
-    private static _worldEulerBuffer: Euler = new Euler();
-    private _worldPosition: Vector3 | undefined = undefined;
-    private _worldQuaternion: Quaternion | undefined = undefined;
-    private static _tempQuaternionBuffer2: Quaternion = new Quaternion();
-    private _worldEuler: Euler | undefined = undefined;
-    private _worldRotation: Vector3 | undefined = undefined;
     get worldPosition(): Vector3 {
-        if (!this._worldPosition) this._worldPosition = new Vector3();
-        threeutils.getWorldPosition(this.gameObject, this._worldPosition);
-        // this.gameObject.getWorldPosition(this._worldPosition);
-        return this._worldPosition;
+        return threeutils.getWorldPosition(this.gameObject);
     }
     set worldPosition(val: Vector3) {
@@ -596,48 +581,33 @@
     }
     setWorldPosition(x: number, y: number, z: number) {
-        Component._worldPositionBuffer.set(x, y, z);
-        this.worldPosition = Component._worldPositionBuffer;
+        threeutils.setWorldPositionXYZ(this.gameObject, x, y, z);
     }
     get worldQuaternion(): Quaternion {
-        if (!this._worldQuaternion) this._worldQuaternion = new Quaternion();
-        return threeutils.getWorldQuaternion(this.gameObject, this._worldQuaternion);
+        return threeutils.getWorldQuaternion(this.gameObject);
     }
     set worldQuaternion(val: Quaternion) {
         threeutils.setWorldQuaternion(this.gameObject, val);
     }
     setWorldQuaternion(x: number, y: number, z: number, w: number) {
-        Component._worldQuaternionBuffer.set(x, y, z, w);
-        this.worldQuaternion = Component._worldQuaternionBuffer;
+        threeutils.setWorldQuaternionXYZW(this.gameObject, x, y, z, w);
     }
     // world euler (in radians)
     get worldEuler(): Euler {
-        if (!this._worldEuler) this._worldEuler = new Euler();
-        this._worldEuler.setFromQuaternion(this.worldQuaternion);
-        return this._worldEuler;
+        return threeutils.getWorldEuler(this.gameObject);
     }
     // world euler (in radians)
     set worldEuler(val: Euler) {
-        if (!this._worldQuaternion) this._worldQuaternion = new Quaternion();
-        this._worldQuaternion?.setFromEuler(val);
-        this.worldQuaternion = this._worldQuaternion;
+        threeutils.setWorldEuler(this.gameObject, val);
     }
     // returns rotation in degrees
     get worldRotation(): Vector3 {
-        const rot = this.worldEuler;
-        if (!this._worldRotation) this._worldRotation = new Vector3();
-        const wr = this._worldRotation;
-        wr.set(rot.x, rot.y, rot.z);
-        wr.x = Mathf.toDegrees(wr.x);
-        wr.y = Mathf.toDegrees(wr.y);
-        wr.z = Mathf.toDegrees(wr.z);
-        return wr;
+        return this.gameObject.worldRotation;;
     }
     set worldRotation(val: Vector3) {
@@ -645,14 +615,7 @@
     }
     setWorldRotation(x: number, y: number, z: number, degrees: boolean = true) {
-        if (degrees) {
-            x = Mathf.toRadians(x);
-            y = Mathf.toRadians(y);
-            z = Mathf.toRadians(z);
-        }
-        Component._worldEulerBuffer.set(x, y, z);
-        Component._worldQuaternionBuffer.setFromEuler(Component._worldEulerBuffer);
-        this.worldQuaternion = Component._worldQuaternionBuffer;
+        threeutils.setWorldRotationXYZ(this.gameObject, x, y, z, degrees);
     }
     private static _forward: Vector3 = new Vector3();

src/engine/engine_instancing.ts CHANGED Viewed

@@ -1,13 +1,31 @@
+import { InstancedMesh, Object3D } from "three";
 export const NEED_UPDATE_INSTANCE_KEY = Symbol("NEEDLE_NEED_UPDATE_INSTANCE");
 export const $isUsingInstancing = Symbol("isUsingInstancing");
+export const $instancingRenderer = Symbol("instancingRenderer");
+export const $instancingAutoUpdateBounds = Symbol("instancingAutoUpdateBounds");
 export class InstancingUtil {
-    static isUsingInstancing(instance: THREE.Object3D): boolean { return instance[$isUsingInstancing] === true; }
+    /** Is this object rendered using a InstancedMesh */
+    static isUsingInstancing(instance: Object3D): boolean { return instance[$isUsingInstancing] === true; }
+    /** Returns the instanced mesh IF the object is rendered by an instanced mesh
+     * @link https://threejs.org/docs/#api/en/objects/InstancedMesh
+     */
+    static getRenderer(instance: Object3D): InstancedMesh | null { return instance[$instancingRenderer] || null; }
+    setAutoUpdateBounds(instance: Object3D, value: boolean) {
+        const renderer = InstancingUtil.getRenderer(instance);
+        if (renderer) {
+            renderer[$instancingAutoUpdateBounds] = value;
+        }
+    }
     // TODO: change this so it does not set matrix world directly but some flag that is only used by instancing
-    static markDirty(go: THREE.Object3D | null, recursive: boolean = true) {
+    /** Mark an instanced object dirty so the instance matrix will be updated */
+    static markDirty(go: Object3D | null, recursive: boolean = true) {
         if (!go) return;
         // potential optimization:
         // if(go.matrixWorldNeedsUpdate) return;

src/engine/engine_physics.ts CHANGED Viewed

@@ -11,25 +11,62 @@
 export declare type RaycastTestObjectReturnType = void | boolean | "continue in children";
 export declare type RaycastTestObjectCallback = (obj: Object3D) => RaycastTestObjectReturnType;
-export class RaycastOptions {
-    ray: Ray | undefined = undefined;
-    cam: Camera | undefined | null = undefined;
-    screenPoint: Vector2 | undefined = undefined;
-    raycaster: Raycaster | undefined = undefined;
-    results: Array<Intersection> | undefined = undefined;
-    targets: Array<Object3D> | undefined = undefined;
-    recursive: boolean | undefined = true;
-    minDistance: number | undefined = undefined;
-    maxDistance: number | undefined = undefined;
-    lineThreshold: number | undefined = undefined;
+declare interface IRaycastOptions {
+    /** Optionally a custom raycaster can be provided. Other properties will then be set on this raycaster */
+    raycaster?: Raycaster;
+    /** Optional ray that can be used for raycasting
+     *  @link https://threejs.org/docs/#api/en/math/Ray
+     * */
+    ray?: Ray;
+    /** The camera to use for the raycaster */
+    cam?: Camera | null;
+    /** Point on screen in raycast space / normalized device coordinates (-1 to 1).
+     * @link https://threejs.org/docs/#api/en/core/Raycaster.setFromCamera */
+    screenPoint?: Vector2;
+    /** Raycast results array. You can provide an array here to avoid creating a new one (note that if your array already contains items they will be removed) */
+    results?: Array<Intersection>;
+    /** Objects to raycast against. If no target array is provided the whole scene will be raycasted */
+    targets?: Array<Object3D>;
+    recursive?: boolean;
+    /** Set the raycaster near distance:
+     * The near factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be smaller than the far property.
+     * @link https://threejs.org/docs/#api/en/core/Raycaster.near
+     */
+    minDistance?: number;
+    /** Set the raycaster far distance:
+     * The far factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be larger than the near property.
+     * @link https://threejs.org/docs/#api/en/core/Raycaster.far
+     */
+    maxDistance?: number;
+    /** @link https://threejs.org/docs/#api/en/core/Raycaster.params */
+    lineThreshold?: number;
     /** raw layer mask, use setLayer to set an individual layer active */
-    layerMask: Layers | number | undefined = undefined;
-    ignore: Object3D[] | undefined = undefined;
-    /** if defined it's called per object before tested for intersections.
+    layerMask?: Layers | number;
+    ignore?: Object3D[];
+    /** Optional calback function to be called per object before tested for intersections.
+     * This can be used to filter objects.
      * Return `false` to ignore the object completely or `"continue in children"` to skip the object but continue to traverse its children (if you do raycast with `recursive` enabled)
      * */
-    testObject?: RaycastTestObjectCallback = undefined;
+    testObject?: RaycastTestObjectCallback;
+}
+export class RaycastOptions implements IRaycastOptions {
+    public static readonly AllLayers = 0xFFFFFFFF;
+    ray?: Ray;
+    cam?: Camera | null;
+    screenPoint?: Vector2;
+    raycaster?: Raycaster;
+    results?: Array<Intersection>;
+    targets?: Array<Object3D>;
+    recursive?: boolean = true;
+    minDistance?: number;
+    maxDistance?: number;
+    lineThreshold?: number;
+    layerMask?: Layers | number;
+    ignore?: Object3D[];
+    testObject?: RaycastTestObjectCallback;
     screenPointFromOffset(ox: number, oy: number) {
         if (this.screenPoint === undefined) this.screenPoint = new Vector2();
         this.screenPoint.x = ox / window.innerWidth * 2 - 1;
@@ -51,7 +88,6 @@
         else this.layerMask = mask;
     }
-    public static readonly AllLayers = 0xFFFFFFFF;
 }
 export class SphereIntersection implements Intersection {
@@ -154,7 +190,10 @@
     public raycastFromRay(ray: Ray, options: RaycastOptions | null = null): Array<Intersection> {
         const opts = options ?? this.defaultRaycastOptions;
         opts.ray = ray;
-        return this.raycast(opts);
+        const res = this.raycast(opts);
+        // reset the default options ray
+        if (opts === this.defaultRaycastOptions) opts.ray = undefined;
+        return res;
     }
     /** raycast against rendered three objects. This might be very slow depending on your scene complexity.
@@ -163,7 +202,7 @@
      * Use raycastPhysics for raycasting against physic colliders only. Depending on your scenario this might be faster.
      * @param options raycast options. If null, default options will be used.
      */
-    public raycast(options: RaycastOptions | null = null): Array<Intersection> {
+    public raycast(options: IRaycastOptions | RaycastOptions | null = null): Array<Intersection> {
         if (!options) options = this.defaultRaycastOptions;
         const mp = options.screenPoint ?? this.context.input.mousePositionRC;
         const rc = options.raycaster ?? this.raycaster;
@@ -230,7 +269,7 @@
         return results;
     }
-    private intersect(raycaster: Raycaster, objects: Object3D[], results: Intersection[], options: RaycastOptions) {
+    private intersect(raycaster: Raycaster, objects: Object3D[], results: Intersection[], options: IRaycastOptions) {
         for (const obj of objects) {
             const testResult = options.testObject?.(obj);
             if (testResult === false) continue;
@@ -239,7 +278,7 @@
                 raycaster.intersectObject(obj, false, results);
             }
-            if (options.recursive) {
+            if (options.recursive !== false) {
                 this.intersect(raycaster, obj.children, results, options);
             }
         }

src/engine-components/ui/Image.ts CHANGED Viewed

@@ -48,7 +48,7 @@
         }
         // this is a hack/workaround for production builds where the name of the sprite is missing
         // need to remove this!!!!
-        if (this.sprite?.texture?.image?.width === 32 && this.sprite?.texture?.image?.height === 32)
+        if (!this.sprite?.texture?.name?.length && this.sprite?.texture?.image?.width === 32 && this.sprite?.texture?.image?.height === 32)
             return true;
         return false;
     }

src/engine-components/ParticleSystem.ts CHANGED Viewed

@@ -12,7 +12,7 @@
 import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldScale } from "../engine/engine_three_utils.js";
 import { assign } from "../engine/engine_serialization_core.js";
 import { ParticleSystem as _ParticleSystem, ConstantValue, ConstantColor, BatchedParticleRenderer, TrailBatch, TrailParticle, RenderMode } from "three.quarks";
-import type { BatchedRenderer, Behavior, BillBoardSettings, BurstParameters, ColorGenerator, EmissionState, EmitSubParticleSystem, EmitterShape, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, IntervalValue, MeshSettings, Particle, ParticleEmitter, ParticleSystemParameters, PointEmitter, RecordState, RotationGenerator, SizeOverLife, TrailSettings, ValueGenerator } from "three.quarks";
+import type { BatchedRenderer, Behavior, BehaviorPlugin, BillBoardSettings, BurstParameters, ColorGenerator, EmissionState, EmitSubParticleSystem, EmitterShape, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, IntervalValue, MeshSettings, Particle, ParticleEmitter, ParticleSystemParameters, PointEmitter, RecordState, RotationGenerator, SizeOverLife, TrailSettings, VFXBatchSettings, ValueGenerator } from "three.quarks";
 import { createFlatTexture } from "../engine/engine_shaders.js";
 import { Mathf } from "../engine/engine_math.js";
 import { Context } from "../engine/engine_setup.js";
@@ -25,6 +25,11 @@
 const suppressProgressiveLoading = getParam("noprogressive");
 const debugProgressiveLoading = getParam("debugprogressive");
+export type { Behavior as QParticleBehaviour, Particle as QParticle } from "three.quarks"
 export enum SubEmitterType {
     Birth = 0,
     Collision = 1,
@@ -248,29 +253,25 @@
     }
 }
-abstract class ParticleSystemBaseBehaviour implements Behavior {
-    readonly system: ParticleSystem;
+export abstract class ParticleSystemBaseBehaviour implements Behavior {
-    // get scaleFactorDiff(): number {
-    //     return this.system.scale - this.system.worldScale.x;
-    // }
+    system!: ParticleSystem;
+    get context() { return this.system.context; }
-    constructor(ps: ParticleSystem) {
-        this.system = ps;
+    constructor(ps?: ParticleSystem) {
+        this.type = Object.getPrototypeOf(this).constructor.name || "ParticleSystemBaseBehaviour";
+        if (ps)
+            this.system = ps;
     }
-    abstract type: string;
+    type: string;
-    initialize(_particle: Particle): void {
-    }
-    update(_particle: Particle, _delta: number): void {
-    }
-    frameUpdate(_delta: number): void {
-    }
+    initialize(_particle: Particle): void { }
+    update(_particle: Particle, _delta: number): void { }
+    frameUpdate(_delta: number): void { }
     toJSON() { throw new Error("Method not implemented."); }
     clone(): Behavior { throw new Error("Method not implemented."); }
-    reset() {
-    }
+    reset() { }
 }
 const $startFrame = Symbol("startFrame")
@@ -843,6 +844,42 @@
         return this._isUsedAsSubsystem;
     }
+    /** Add a custom quarks behaviour to the particle system. You can add a quarks.Behaviour type.
+     * @link https://github.com/Alchemist0823/three.quarks
+    */
+    addBehaviour(particleSystemBehaviour: Behavior | ParticleSystemBaseBehaviour): boolean {
+        if (!this._particleSystem) {
+            return false;
+        }
+        if (particleSystemBehaviour instanceof ParticleSystemBaseBehaviour) {
+            particleSystemBehaviour.system = this;
+        }
+        if (isDevEnvironment()) console.log("add behaviour", particleSystemBehaviour);
+        this._particleSystem.addBehavior(particleSystemBehaviour);
+        return true;
+    }
+    /** Removes all behaviours from the particle system
+     * **Note:** this will also remove the default behaviours like SizeBehaviour, ColorBehaviour etc.
+     */
+    removeAllBehaviours() {
+        if (!this._particleSystem) {
+            return false;
+        }
+        this._particleSystem.behaviors.length = 0;
+        return true;
+    }
+    /** Get the particlesystem behaviours. This can be used to fully customize the behaviour of the particles. */
+    get behaviours(): Behavior[] | null {
+        if (!this._particleSystem) return null;
+        return this._particleSystem.behaviors;
+    }
+    /** Get access to the underlying quarks particle system if you need more control
+     * @link https://github.com/Alchemist0823/three.quarks
+     */
+    get particleSystem(): _ParticleSystem | null {
+        return this._particleSystem ?? null;
+    }
     private _renderer!: ParticleSystemRenderer;
     private _batchSystem?: BatchedRenderer;
     private _particleSystem?: _ParticleSystem;

src/engine/codegen/register_types.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { TypeStore } from "./../engine_typestore.js"
 // Import types
 import { __Ignore } from "../../engine-components/codegen/components.js";
 import { ActionBuilder } from "../../engine-components/export/usdz/extensions/behavior/BehavioursBuilder.js";
@@ -219,7 +219,7 @@
 import { XRGrabRendering } from "../../engine-components/webxr/WebXRGrabRendering.js";
 import { XRRig } from "../../engine-components/webxr/WebXRRig.js";
 import { XRState } from "../../engine-components/XRFlag.js";
 // Register types
 TypeStore.add("__Ignore", __Ignore);
 TypeStore.add("ActionBuilder", ActionBuilder);

src/engine-components/Renderer.ts CHANGED Viewed

@@ -8,7 +8,7 @@
 import { AxesHelper, Material, Matrix4, Mesh, Object3D, SkinnedMesh, Texture, Vector4 } from "three";
 import { NEEDLE_render_objects } from "../engine/extensions/NEEDLE_render_objects.js";
 import { NEEDLE_progressive } from "../engine/extensions/NEEDLE_progressive.js";
-import { InstancingUtil, NEED_UPDATE_INSTANCE_KEY } from "../engine/engine_instancing.js";
+import { $instancingAutoUpdateBounds, $instancingRenderer, InstancingUtil, NEED_UPDATE_INSTANCE_KEY } from "../engine/engine_instancing.js";
 import type { IRenderer, ISharedMaterials } from "../engine/engine_types.js";
 import { ReflectionProbe } from "./ReflectionProbe.js";
 import { setCustomVisibility } from "../engine/js-extensions/Layers.js";
@@ -912,8 +912,8 @@
         this.instanceIndex = instanceIndex;
         this.object = originalObject;
         this.instancer = instancer;
+        originalObject[$instancingRenderer] = instancer;
         GameObject.markAsInstancedRendered(originalObject, true);
-        // this.object.visible = false;
     }
     updateInstanceMatrix(updateChildren: boolean = false) {
@@ -939,7 +939,21 @@
 }
 class InstancedMeshRenderer {
+    /** The three instanced mesh
+     * @link https://threejs.org/docs/#api/en/objects/InstancedMesh
+     */
+    get mesh() {
+        return this.inst;
+    }
+    get visible(): boolean {
+        return this.inst.visible;
+    }
+    set visible(val: boolean) {
+        this.inst.visible = val;
+    }
+    get castShadow(): boolean {
+        return this.inst.castShadow;
+    }
     set castShadow(val: boolean) {
         this.inst.castShadow = val;
     }
@@ -947,6 +961,14 @@
         this.inst.receiveShadow = val;
     }
+    updateBounds(box: boolean = true, sphere: boolean = true) {
+        this._needUpdateBounds = false;
+        if (box)
+            this.inst.computeBoundingBox();
+        if (sphere)
+            this.inst.computeBoundingSphere();
+    }
     public name: string = "";
     public geo: THREE.BufferGeometry;
     public material: THREE.Material;
@@ -963,6 +985,8 @@
         return this.currentCount >= this.maxCount;
     }
+    private _needUpdateBounds: boolean = false;
     constructor(name: string, geo: THREE.BufferGeometry, material: THREE.Material, count: number, context: Context) {
         this.name = name;
         this.geo = geo;
@@ -973,9 +997,18 @@
             material = new THREE.MeshBasicMaterial({ color: this.randomColor() });
         }
         this.inst = new THREE.InstancedMesh(geo, material, count);
+        this.inst[$instancingAutoUpdateBounds] = true;
+        this.inst.onBeforeRender = () => {
+            if (this._needUpdateBounds && this.inst[$instancingAutoUpdateBounds] === true) {
+                if (debugInstancing)
+                    console.log("Update instancing bounds", this.name);
+                this.updateBounds();
+            }
+        };
         this.inst.count = 0;
         this.inst.layers.set(2);
         this.inst.visible = true;
         // this.inst.castShadow = true;
         // this.inst.receiveShadow = true;
         this.context.scene.add(this.inst);
@@ -1023,6 +1056,7 @@
         this.inst.setMatrixAt(handle.instanceIndex, handle.object.matrixWorld);
         this.inst.instanceMatrix.needsUpdate = true;
         this.inst.count += 1;
+        this._needUpdateBounds = true;
         if (this.inst.count > 0)
             this.inst.visible = true;
@@ -1061,6 +1095,7 @@
         if (this.inst.count > 0)
             this.inst.count -= 1;
         handle.instanceIndex = -1;
+        this._needUpdateBounds = true;
         if (this.inst.count <= 0)
             this.inst.visible = false;
@@ -1071,5 +1106,6 @@
     updateInstance(mat: THREE.Matrix4, index: number) {
         this.inst.setMatrixAt(index, mat);
         this.inst.instanceMatrix.needsUpdate = true;
+        this._needUpdateBounds = true;
     }
 }

src/engine-components/RigidBody.ts CHANGED Viewed

@@ -137,6 +137,9 @@
     @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;
@@ -166,10 +169,12 @@
     @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;
@@ -178,58 +183,77 @@
     @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;
     }
@@ -240,7 +264,7 @@
     private _gravityScale: number = 1;
     /** Rigidbodies with higher dominance will be immune to forces originating from contacts with rigidbodies of lower dominance.
-     * Read more here: https://rapier.rs/docs/user_guides/javascript/rigid_bodies#dominance
+     * @link https://rapier.rs/docs/user_guides/javascript/rigid_bodies#dominance
      */
     @validate()
     dominanceGroup : number = 0;
@@ -299,6 +323,7 @@
         }
     }
+    /** 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);
@@ -325,18 +350,27 @@
         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") {
@@ -349,6 +383,8 @@
         }
     }
+    /** 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);
@@ -368,6 +404,17 @@
         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;
@@ -378,35 +425,24 @@
         this.context.physics.engine?.setAngularVelocity(this, { x: x, y: y, z: z }, wakeup);
     }
-    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;
-    }
+    /** 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);
     }
-    // public get smoothedVelocity() { return this._smoothedVelocity; }
     /**d
-     * @deprecated not used anymore
+     * @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);