@gg-web-engine/rapier3d 0.0.72 → 0.0.74

package/dist/components/rapier-3d-character-controller.component.d.ts

@@ -1,4 +1,4 @@
-import { CharacterController3dOptions, CollisionGroup, DebugBody3DSettings, Entity3d, ICharacterController3dComponent, Point3, Point4 } from '@gg-web-engine/core';
+import { CharacterController3dOptions, CollisionGroup, DebugBody3DSettings, ICharacterController3dComponent, IEntity, Point3, Point4 } from '@gg-web-engine/core';
 import { Collider, InteractionGroups, KinematicCharacterController, RigidBody, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 import { Rapier3dWorldComponent } from './rapier-3d-world.component';
 import { Rapier3dRigidBodyComponent } from './rapier-3d-rigid-body.component';
@@ -22,18 +22,23 @@ import { Rapier3dGgWorld, Rapier3dPhysicsTypeDocRepo } from '../types';
  * specific to this component; a normal per-frame game loop that calls `physicsWorld.simulate()`
  * every tick already satisfies it after the first tick.
  *
- * Note: unlike `Rapier3dRigidBodyComponent`/`Rapier3dTriggerComponent`, this component's native body
- * handle is *not* registered in `Rapier3dWorldComponent.handleIdEntityMap` - `world.raycast()` cannot
- * currently resolve a hit against a character controller back to this component (it will simply be
- * absent from `RaycastResult.hitBody`). Wiring that up would require widening the reverse-map's and
- * `raycast()`'s return-type generics repo-wide for a corner case outside this interface's contract;
- * left as a documented limitation rather than done speculatively.
+ * Note: this component's native body handle *is* registered in
+ * `Rapier3dWorldComponent.handleIdEntityMap` (see `addToWorld`/`removeFromWorld` below), alongside
+ * ordinary `Rapier3dRigidBodyComponent`/`Rapier3dTriggerComponent` handles - this is what lets a
+ * `Trigger3dEntity`'s `onEntityEntered`/`onEntityLeft` fire for a player walking through it, not just
+ * for ordinary rigid bodies/vehicle chassis (`Rapier3dWorldComponent.dispatchCollisionEvents` resolves
+ * a sensor-overlap pair's components through this same map). `world.raycast()` deliberately still does
+ * *not* resolve a hit against a character controller back to this component (filtered out in
+ * `raycast()` itself) - widening that too would mean widening the public `raycast()` return-type
+ * generic repo-wide for a case outside `IPhysicsWorldComponent.raycast`'s own documented contract
+ * (`PTypeDoc['rigidBody'] | PTypeDoc['trigger']`), so it's left resolving to `hitBody: undefined`
+ * there, same as before.
  */
 export declare class Rapier3dCharacterControllerComponent implements ICharacterController3dComponent<Rapier3dPhysicsTypeDocRepo> {
     protected readonly world: Rapier3dWorldComponent;
     protected readonly options: Required<CharacterController3dOptions>;
     protected _bodyDescr: RigidBodyDesc;
-    entity: Entity3d | null;
+    entity: IEntity | null;
     name: string;
     readonly radius: number;
     readonly centersDistance: number;

package/dist/components/rapier-3d-character-controller.component.js

@@ -1,5 +1,5 @@
 import { BitMask, DebugBody3DSettings, Pnt3, Qtrn, warnOnce, } from '@gg-web-engine/core';
-import { Quaternion, RigidBodyDesc, Vector3, } from '@dimforge/rapier3d-compat';
+import { ActiveCollisionTypes, ActiveEvents, QueryFilterFlags, Quaternion, RigidBodyDesc, Vector3, } from '@dimforge/rapier3d-compat';
 /**
  * A capsule-shaped kinematic character controller backed by Rapier's own `KinematicCharacterController`
  * (`world.createCharacterController`). `move()` is made fully synchronous (see
@@ -19,12 +19,17 @@ import { Quaternion, RigidBodyDesc, Vector3, } from '@dimforge/rapier3d-compat';
  * specific to this component; a normal per-frame game loop that calls `physicsWorld.simulate()`
  * every tick already satisfies it after the first tick.
  *
- * Note: unlike `Rapier3dRigidBodyComponent`/`Rapier3dTriggerComponent`, this component's native body
- * handle is *not* registered in `Rapier3dWorldComponent.handleIdEntityMap` - `world.raycast()` cannot
- * currently resolve a hit against a character controller back to this component (it will simply be
- * absent from `RaycastResult.hitBody`). Wiring that up would require widening the reverse-map's and
- * `raycast()`'s return-type generics repo-wide for a corner case outside this interface's contract;
- * left as a documented limitation rather than done speculatively.
+ * Note: this component's native body handle *is* registered in
+ * `Rapier3dWorldComponent.handleIdEntityMap` (see `addToWorld`/`removeFromWorld` below), alongside
+ * ordinary `Rapier3dRigidBodyComponent`/`Rapier3dTriggerComponent` handles - this is what lets a
+ * `Trigger3dEntity`'s `onEntityEntered`/`onEntityLeft` fire for a player walking through it, not just
+ * for ordinary rigid bodies/vehicle chassis (`Rapier3dWorldComponent.dispatchCollisionEvents` resolves
+ * a sensor-overlap pair's components through this same map). `world.raycast()` deliberately still does
+ * *not* resolve a hit against a character controller back to this component (filtered out in
+ * `raycast()` itself) - widening that too would mean widening the public `raycast()` return-type
+ * generic repo-wide for a case outside `IPhysicsWorldComponent.raycast`'s own documented contract
+ * (`PTypeDoc['rigidBody'] | PTypeDoc['trigger']`), so it's left resolving to `hitBody: undefined`
+ * there, same as before.
  */
 export class Rapier3dCharacterControllerComponent {
     get up() {
@@ -211,7 +216,18 @@ export class Rapier3dCharacterControllerComponent {
             }
         }
         const desired = new Vector3(desiredTranslation.x, desiredTranslation.y, desiredTranslation.z);
-        this._nativeController.computeColliderMovement(this._nativeCollider, desired, undefined, undefined, this.ignoredBodiesFilterPredicate());
+        this._nativeController.computeColliderMovement(this._nativeCollider, desired, 
+        // `computeColliderMovement`'s own default (no `filterFlags`) treats a sensor collider as a
+        // solid obstacle, exactly like any real one - confirmed empirically (a character walking
+        // straight at a `Trigger`'s volume physically stopped dead at its boundary instead of walking
+        // through it, well before Rapier's own `KINEMATIC_FIXED` intersection event ever had a chance
+        // to fire - see `Rapier3dWorldComponent.handleIdEntityMap`'s doc for that separate, now also
+        // fixed, half of this). `EXCLUDE_SENSORS` is required so a character can walk into/through a
+        // trigger's volume at all, matching what "trigger" means everywhere else in this engine (a
+        // sensor with no collision response, see `ITrigger3dComponent`) and what `AmmoCharacterControllerComponent`'s
+        // own sweep-based mover already does (Ammo's `CF_NO_CONTACT_RESPONSE` ghost trigger was never a
+        // solid obstacle to begin with).
+        QueryFilterFlags.EXCLUDE_SENSORS, undefined, this.ignoredBodiesFilterPredicate());
         const computed = this._nativeController.computedMovement();
         const current = this._nativeBody.translation();
         const next = new Vector3(current.x + computed.x, current.y + computed.y, current.z + computed.z);
@@ -352,6 +368,11 @@ export class Rapier3dCharacterControllerComponent {
         bd.setTranslation(pos.x, pos.y, pos.z);
         bd.setRotation(new Quaternion(rot.x, rot.y, rot.z, rot.w));
         const comp = new Rapier3dCharacterControllerComponent(this.world, this.options, bd);
+        // `this.options.up` is only ever read once, in the constructor - the live `up` setter (used by
+        // any caller that rotates the character after construction) never writes back to it, so it goes
+        // stale the moment `up` changes; copy the CURRENT value here instead, the same way
+        // `collisionGroups` already does below.
+        comp.up = this.up;
         comp.collisionGroups = this.collisionGroups;
         return comp;
     }
@@ -366,6 +387,24 @@ export class Rapier3dCharacterControllerComponent {
             radius: this.radius,
             centersDistance: this.centersDistance,
         })[0];
+        // Both needed for `Rapier3dWorldComponent.dispatchCollisionEvents` to ever see a pair involving
+        // this character controller (sensor overlap *or* real contact):
+        // - `ActiveCollisionTypes` gates which pairs even reach narrow-phase at all, gated by the two
+        //   bodies' *rigid-body* types - Rapier's own default (`ActiveCollisionTypes.DEFAULT`) is only
+        //   `DYNAMIC_DYNAMIC | DYNAMIC_FIXED | DYNAMIC_KINEMATIC`; this `kinematicPositionBased` body
+        //   paired against a `static` trigger is `KINEMATIC_FIXED`, which `DEFAULT` excludes entirely -
+        //   confirmed empirically (a character parked motionless inside a trigger's volume for a full
+        //   second of simulated time never fired `onEntityEntered` until this was set). `.ALL` covers
+        //   every other rigid-body-type combination this character could ever meet too (another
+        //   kinematic character, a `Trigger` that's itself kinematic, etc.), not just this one pairing.
+        // - `ActiveEvents.COLLISION_EVENTS` is the separate, per-*collider*, "actually emit an event for
+        //   an allowed pair" flag - a trigger's own sensor collider already sets it (see
+        //   `Rapier3dFactory.createTrigger`) and one side being enough is normally sufficient (see
+        //   `Rapier3dFactory.createRigidBody`'s doc), but this collider sets it too regardless, so a real
+        //   (non-sensor) contact against another kinematic body - which would have neither side pre-set -
+        //   still produces events consistently.
+        colliderDescr.setActiveCollisionTypes(ActiveCollisionTypes.ALL);
+        colliderDescr.setActiveEvents(ActiveEvents.COLLISION_EVENTS);
         this._nativeCollider = nativeWorld.createCollider(colliderDescr, this._nativeBody);
         this._nativeCollider.setCollisionGroups(this.collisionGroups);
         this._nativeController = nativeWorld.createCharacterController(this.options.offset);
@@ -377,6 +416,7 @@ export class Rapier3dCharacterControllerComponent {
         if (this.options.snapToGroundDistance > 0) {
             this._nativeController.enableSnapToGround(this.options.snapToGroundDistance);
         }
+        this.world.handleIdEntityMap.set(this._nativeBody.handle, this);
         // Rapier's own `KinematicCharacterController` has a built-in equivalent of `pushMass`
         // (`setApplyImpulsesToDynamicBodies(true)` + `setCharacterMass(...)`) that looked like the
         // obvious way to implement pushing here - no hand-rolled logic needed, unlike
@@ -405,6 +445,7 @@ export class Rapier3dCharacterControllerComponent {
             this._nativeController = null;
         }
         if (this._nativeBody) {
+            this.world.handleIdEntityMap.delete(this._nativeBody.handle);
             if (this._nativeCollider) {
                 this.world.nativeWorld.removeCollider(this._nativeCollider, false);
                 this._nativeCollider = null;

package/dist/components/rapier-3d-raycast-vehicle.component.d.ts

@@ -3,26 +3,71 @@ import { DynamicRayCastVehicleController } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './rapier-3d-rigid-body.component';
 import { Rapier3dWorldComponent } from './rapier-3d-world.component';
 import { Rapier3dGgWorld, Rapier3dPhysicsTypeDocRepo } from '../types';
+/**
+ * Rapier's `DynamicRayCastVehicleController` (`world.createVehicleController`) is a thin wrapper
+ * around wheel raycasting only - nothing steps it automatically as part of `World.step()`.
+ * Instead, `updateVehicle(dt, ...)` must be called once per tick *before* `world.step()` - it directly writes the chassis's own
+ * `linvel`/`angvel` from that tick's suspension/engine/brake forces, which `world.step()` then
+ * integrates like any other dynamic body's velocity. This component registers itself into
+ * `Rapier3dWorldComponent.raycastVehicles` on `addToWorld`/`removeFromWorld` so the world component
+ * can drive that call centrally from `simulate()` - see that class's doc.
+ *
+ * Like `Rapier3dCharacterControllerComponent`/`Rapier3dTriggerComponent`, this class and
+ * `Rapier3dWorldComponent` import each other (the world needs this class purely as a type for its
+ * `raycastVehicles` set, the vehicle needs the world's concrete type for its constructor/`addToWorld`
+ * parameter) - this circular import is an established, safe pattern in this package (see those two
+ * classes), not specific to this one.
+ */
 export declare class Rapier3dRaycastVehicleComponent extends Rapier3dRigidBodyComponent implements IRaycastVehicleComponent<Rapier3dPhysicsTypeDocRepo> {
     protected readonly world: Rapier3dWorldComponent;
     private chassisBody;
     protected _nativeVehicle: DynamicRayCastVehicleController | null;
     get nativeVehicle(): DynamicRayCastVehicleController | null;
-    private wheelDescr;
+    private readonly wheels;
     constructor(world: Rapier3dWorldComponent, chassisBody: Rapier3dRigidBodyComponent);
     get wheelSpeed(): number;
     addToWorld(world: Rapier3dGgWorld): void;
     removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
+    /**
+     * Called once per `simulate()` tick by `Rapier3dWorldComponent`, *before* `World.step()` - see
+     * this class's own doc for why. `filterGroups` threads this vehicle's own collision groups
+     * (`this.collisionGroups`, inherited from `Rapier3dRigidBodyComponent` and already packed in the
+     * `InteractionGroups` layout Rapier expects) into the wheels' own suspension raycasts, so a
+     * vehicle in one collision group doesn't get held up by suspension force from a floor it isn't
+     * meant to interact with - without this, only the chassis's own broadphase collision would
+     * respect collision groups, not the ray-cast-based wheel/ground detection (see
+     * `gg-engine-physics-adapter`'s testing guidance on this). `EXCLUDE_SENSORS` keeps a `Trigger`'s
+     * sensor volume from ever acting as solid ground for a wheel, mirroring
+     * `Rapier3dCharacterControllerComponent.move()`'s identical guard.
+     */
+    stepVehicleController(dt: number): void;
+    private attachWheel;
     addWheel(options: WheelOptions, suspensionOptions: SuspensionOptions): void;
     setSteering(wheelIndex: number, steering: number): void;
     applyEngineForce(wheelIndex: number, force: number): void;
     applyBrake(wheelIndex: number, force: number): void;
     isWheelTouchesGround(wheelIndex: number): boolean;
+    /**
+     * Rapier's controller exposes no single call that bakes suspension travel, steering and roll into
+     * one transform for rendering - only the individual pieces
+     * (`wheelHardPoint`/`wheelSuspensionLength`/`wheelDirectionCs`/`wheelAxleCs`/`wheelSteering`/
+     * `wheelRotation`), which this method composes by hand:
+     * - **Position**: `wheelHardPoint` is already world-space (the ray-cast's own start point, fixed
+     *   relative to the chassis) - moving it `wheelSuspensionLength` further along the *world-space*
+     *   suspension direction (`wheelDirectionCs` rotated by the chassis's current rotation) lands
+     *   exactly on the wheel's current (compressed-by-however-much) center, airborne or grounded alike.
+     * - **Rotation**: composed as chassis rotation ∘ steering (about the chassis's local up axis,
+     *   `Pnt3.Z` - only ever nonzero for wheels `RaycastVehicle3dEntity` actually steers) ∘ roll (about
+     *   this wheel's own configured local axle, `wheelRotation`'s accumulated spin angle). This is a
+     *   best-effort reconstruction, not something read back verbatim from the native engine - document
+     *   as a known limitation rather than chasing exactness, same spirit as
+     *   `Rapier3dCharacterControllerComponent`'s ground-normal approximation.
+     */
     getWheelTransform(wheelIndex: number): {
         position: Point3;
         rotation: Point4;
     };
     resetSuspension(): void;
     clone(): Rapier3dRaycastVehicleComponent;
-    dispose(): void;
+    resetMotion(): void;
 }

package/dist/components/rapier-3d-raycast-vehicle.component.js

@@ -1,6 +1,21 @@
 import { Pnt3, Qtrn, } from '@gg-web-engine/core';
-import { Vector3 } from '@dimforge/rapier3d-compat';
+import { QueryFilterFlags } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './rapier-3d-rigid-body.component';
+/**
+ * Rapier's `DynamicRayCastVehicleController` (`world.createVehicleController`) is a thin wrapper
+ * around wheel raycasting only - nothing steps it automatically as part of `World.step()`.
+ * Instead, `updateVehicle(dt, ...)` must be called once per tick *before* `world.step()` - it directly writes the chassis's own
+ * `linvel`/`angvel` from that tick's suspension/engine/brake forces, which `world.step()` then
+ * integrates like any other dynamic body's velocity. This component registers itself into
+ * `Rapier3dWorldComponent.raycastVehicles` on `addToWorld`/`removeFromWorld` so the world component
+ * can drive that call centrally from `simulate()` - see that class's doc.
+ *
+ * Like `Rapier3dCharacterControllerComponent`/`Rapier3dTriggerComponent`, this class and
+ * `Rapier3dWorldComponent` import each other (the world needs this class purely as a type for its
+ * `raycastVehicles` set, the vehicle needs the world's concrete type for its constructor/`addToWorld`
+ * parameter) - this circular import is an established, safe pattern in this package (see those two
+ * classes), not specific to this one.
+ */
 export class Rapier3dRaycastVehicleComponent extends Rapier3dRigidBodyComponent {
     get nativeVehicle() {
         return this._nativeVehicle;
@@ -10,86 +25,179 @@ export class Rapier3dRaycastVehicleComponent extends Rapier3dRigidBodyComponent
         this.world = world;
         this.chassisBody = chassisBody;
         this._nativeVehicle = null;
-        this.wheelDescr = [];
+        this.wheels = [];
     }
     get wheelSpeed() {
         var _a;
-        return (((_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.currentVehicleSpeed()) || 0) / 3.6;
+        return ((_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.currentVehicleSpeed()) || 0;
     }
     addToWorld(world) {
         super.addToWorld(world);
-        this._nativeVehicle = world.physicsWorld.nativeWorld.createVehicleController(this._nativeBody);
+        const nativeWorld = this.world.nativeWorld;
+        this._nativeVehicle = nativeWorld.createVehicleController(this._nativeBody);
+        // matches this engine's own Z-up/Y-forward convention (see `RaycastVehicle3dEntity`'s own doc:
+        // "car mesh and physics body direction has to be pointing: y front, z up") - axis indices are
+        // 0 = x, 1 = y, 2 = z.
         this._nativeVehicle.indexUpAxis = 2;
+        // this pinned `@dimforge/rapier3d-compat` build's own setter is genuinely named
+        // `setIndexForwardAxis` (a setter *property*, not a typo introduced by this adapter) - see
+        // `ray_cast_vehicle_controller.d.ts`'s `set setIndexForwardAxis(axis: number)`.
         this._nativeVehicle.setIndexForwardAxis = 1;
-        for (const descr of this.wheelDescr) {
-            this._nativeVehicle.addWheel(...descr);
+        for (const wheel of this.wheels) {
+            this.attachWheel(this._nativeVehicle, wheel);
         }
-        setInterval(() => this._nativeVehicle.updateVehicle(0.01), 10);
+        this.world.raycastVehicles.add(this);
     }
     removeFromWorld(world, dispose) {
         if (world.physicsWorld != this.world) {
             throw new Error('Rapier3D bodies cannot be shared between different worlds');
         }
-        if (this.nativeVehicle) {
-            world.physicsWorld.nativeWorld.removeVehicleController(this.nativeVehicle);
+        this.world.raycastVehicles.delete(this);
+        if (this._nativeVehicle) {
+            this.world.nativeWorld.removeVehicleController(this._nativeVehicle);
+            // `removeVehicleController` only unregisters it from the world's own bookkeeping - the JS
+            // wrapper's own native handle still needs an explicit `.free()`, which nothing else ever
+            // reaches (see this class's own doc and `gg-engine-physics-adapter-rapier`). Always freed here
+            // (not gated behind `dispose`, mirroring `Rapier3dRigidBodyComponent.removeFromWorld`'s own
+            // unconditional native cleanup - a vehicle controller isn't reconstructible from a stored
+            // descriptor the way a rigid body is, so keeping a stale, removed-but-unfreed reference around
+            // for a possible future re-`addToWorld` would only leak it, never usefully resurrect it).
+            this._nativeVehicle.free();
+            this._nativeVehicle = null;
         }
         super.removeFromWorld(world, dispose);
-        if (dispose) {
-            this.dispose();
+    }
+    /**
+     * Called once per `simulate()` tick by `Rapier3dWorldComponent`, *before* `World.step()` - see
+     * this class's own doc for why. `filterGroups` threads this vehicle's own collision groups
+     * (`this.collisionGroups`, inherited from `Rapier3dRigidBodyComponent` and already packed in the
+     * `InteractionGroups` layout Rapier expects) into the wheels' own suspension raycasts, so a
+     * vehicle in one collision group doesn't get held up by suspension force from a floor it isn't
+     * meant to interact with - without this, only the chassis's own broadphase collision would
+     * respect collision groups, not the ray-cast-based wheel/ground detection (see
+     * `gg-engine-physics-adapter`'s testing guidance on this). `EXCLUDE_SENSORS` keeps a `Trigger`'s
+     * sensor volume from ever acting as solid ground for a wheel, mirroring
+     * `Rapier3dCharacterControllerComponent.move()`'s identical guard.
+     */
+    stepVehicleController(dt) {
+        if (!this._nativeVehicle) {
+            return;
         }
+        this._nativeVehicle.updateVehicle(dt, QueryFilterFlags.EXCLUDE_SENSORS, this.collisionGroups);
+    }
+    attachWheel(nativeVehicle, wheel) {
+        nativeVehicle.addWheel(wheel.connectionPointCs, wheel.directionCs, wheel.axleCs, wheel.restLength, wheel.radius);
+        const i = nativeVehicle.numWheels() - 1;
+        nativeVehicle.setWheelSuspensionStiffness(i, wheel.suspension.stiffness);
+        nativeVehicle.setWheelSuspensionRelaxation(i, wheel.suspension.damping);
+        nativeVehicle.setWheelSuspensionCompression(i, wheel.suspension.compression);
+        nativeVehicle.setWheelMaxSuspensionTravel(i, wheel.options.maxTravel);
+        nativeVehicle.setWheelFrictionSlip(i, wheel.options.frictionSlip);
+        // Rapier has no single field named "roll influence" - `WheelOptions.rollInfluence` (how much a
+        // wheel resists roll-inducing side force, per `IRaycastVehicleComponent`'s doc) is approximated
+        // with the closest native equivalent, side-friction stiffness. Best-effort, same spirit as
+        // `Rapier3dCharacterControllerComponent`'s documented ground-normal approximation - not
+        // guaranteed to produce an identical feel for a given numeric value across physics engines.
+        nativeVehicle.setWheelSideFrictionStiffness(i, wheel.options.rollInfluence);
     }
     addWheel(options, suspensionOptions) {
-        const descr = [
-            new Vector3(options.position.x, options.position.y, options.position.z),
-            Pnt3.nZ,
-            options.isLeft ? Pnt3.X : Pnt3.nX,
-            suspensionOptions.restLength,
-            options.tyreRadius,
-        ];
-        this.wheelDescr.push(descr);
-        if (this.nativeVehicle) {
-            this.nativeVehicle.addWheel(...descr);
+        const wheel = {
+            connectionPointCs: Pnt3.clone(options.position),
+            directionCs: Pnt3.nZ,
+            // One constant axle for every wheel, left or right. Confirmed empirically that flipping this
+            // per side (an earlier version of this method used `options.isLeft ? Pnt3.X : Pnt3.nX`, on the
+            // theory that it would make `getWheelTransform`'s roll rotation spin each side's mesh the
+            // visually correct way) breaks *driving* outright: Rapier's engine-force/friction model treats
+            // `axleCs` as the wheel's forward-tire-direction reference, so a flipped axle on one side
+            // applies that side's engine force in the opposite world direction from the other side - equal
+            // and opposite forward forces exactly cancel, and the chassis never moves (a real regression
+            // test - drive under engine force and assert net displacement - is what caught this; a
+            // settle-only test cannot, since it never applies engine force at all). Left/right visual
+            // mirroring of the wheel mesh is already handled adapter-agnostically at the entity level
+            // (`RaycastVehicle3dEntity`'s own `wheelLocalRotation`, derived from `WheelOptions.isLeft`), so
+            // `getWheelTransform` below doesn't need to (and must not) compensate for it again itself.
+            axleCs: Pnt3.X,
+            restLength: suspensionOptions.restLength,
+            radius: options.tyreRadius,
+            options,
+            suspension: suspensionOptions,
+        };
+        this.wheels.push(wheel);
+        if (this._nativeVehicle) {
+            this.attachWheel(this._nativeVehicle, wheel);
         }
     }
     setSteering(wheelIndex, steering) {
-        if (!this.nativeVehicle)
-            return;
-        this.nativeVehicle.setWheelSteering(wheelIndex, steering);
+        var _a;
+        (_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.setWheelSteering(wheelIndex, steering);
     }
     applyEngineForce(wheelIndex, force) {
-        if (!this.nativeVehicle)
-            return;
-        this.nativeVehicle.setWheelEngineForce(wheelIndex, force);
+        var _a;
+        (_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.setWheelEngineForce(wheelIndex, force);
     }
     applyBrake(wheelIndex, force) {
-        if (!this.nativeVehicle)
-            return;
-        this.nativeVehicle.setWheelBrake(wheelIndex, force);
+        var _a;
+        (_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.setWheelBrake(wheelIndex, force);
     }
     isWheelTouchesGround(wheelIndex) {
-        if (!this.nativeVehicle)
-            return false;
-        // TODO
-        return true; //this.nativeVehicle.wheelIsInContact(wheelIndex);
+        var _a, _b;
+        return (_b = (_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.wheelIsInContact(wheelIndex)) !== null && _b !== void 0 ? _b : false;
     }
+    /**
+     * Rapier's controller exposes no single call that bakes suspension travel, steering and roll into
+     * one transform for rendering - only the individual pieces
+     * (`wheelHardPoint`/`wheelSuspensionLength`/`wheelDirectionCs`/`wheelAxleCs`/`wheelSteering`/
+     * `wheelRotation`), which this method composes by hand:
+     * - **Position**: `wheelHardPoint` is already world-space (the ray-cast's own start point, fixed
+     *   relative to the chassis) - moving it `wheelSuspensionLength` further along the *world-space*
+     *   suspension direction (`wheelDirectionCs` rotated by the chassis's current rotation) lands
+     *   exactly on the wheel's current (compressed-by-however-much) center, airborne or grounded alike.
+     * - **Rotation**: composed as chassis rotation ∘ steering (about the chassis's local up axis,
+     *   `Pnt3.Z` - only ever nonzero for wheels `RaycastVehicle3dEntity` actually steers) ∘ roll (about
+     *   this wheel's own configured local axle, `wheelRotation`'s accumulated spin angle). This is a
+     *   best-effort reconstruction, not something read back verbatim from the native engine - document
+     *   as a known limitation rather than chasing exactness, same spirit as
+     *   `Rapier3dCharacterControllerComponent`'s ground-normal approximation.
+     */
     getWheelTransform(wheelIndex) {
-        if (!this.nativeVehicle)
+        var _a, _b, _c;
+        if (!this.nativeVehicle) {
             return { position: Pnt3.O, rotation: Qtrn.O };
+        }
         const chassisRotation = this.rotation;
-        return {
-            position: Pnt3.add(this.position, Pnt3.rot(this.nativeVehicle.wheelChassisConnectionPointCs(wheelIndex), chassisRotation)),
-            rotation: chassisRotation,
-        };
+        const hardPoint = this.nativeVehicle.wheelHardPoint(wheelIndex);
+        const directionCs = this.nativeVehicle.wheelDirectionCs(wheelIndex);
+        const suspensionLength = (_a = this.nativeVehicle.wheelSuspensionLength(wheelIndex)) !== null && _a !== void 0 ? _a : 0;
+        let position = Pnt3.O;
+        if (hardPoint && directionCs) {
+            const worldDirection = Pnt3.rot(Pnt3.clone(directionCs), chassisRotation);
+            position = Pnt3.add(Pnt3.clone(hardPoint), Pnt3.scalarMult(worldDirection, suspensionLength));
+        }
+        const axleCs = this.nativeVehicle.wheelAxleCs(wheelIndex);
+        const rollAngle = (_b = this.nativeVehicle.wheelRotation(wheelIndex)) !== null && _b !== void 0 ? _b : 0;
+        const steerAngle = (_c = this.nativeVehicle.wheelSteering(wheelIndex)) !== null && _c !== void 0 ? _c : 0;
+        const rollRotation = axleCs ? Qtrn.rotAround(Qtrn.O, Pnt3.clone(axleCs), rollAngle) : Qtrn.O;
+        const steerRotation = Qtrn.rotAround(Qtrn.O, Pnt3.Z, steerAngle);
+        const rotation = Qtrn.combineRotations(chassisRotation, steerRotation, rollRotation);
+        return { position, rotation };
     }
     resetSuspension() {
-        // TODO
+        // No native equivalent: Rapier doesn't expose a settable "current suspension length" (only the
+        // rest length/travel bounds that shape it). Not load-bearing, either - the very next
+        // `stepVehicleController` tick re-derives every wheel's suspension length from a fresh ray-cast
+        // against the vehicle's (by then already reset) position, so a teleport/respawn recovers on its
+        // own within one tick without this. Kept as a documented no-op purely for interface conformance,
+        // same spirit as other best-effort gaps in this file.
     }
     clone() {
-        return new Rapier3dRaycastVehicleComponent(this.world, this.chassisBody.clone());
+        const comp = new Rapier3dRaycastVehicleComponent(this.world, this.chassisBody.clone());
+        for (const wheel of this.wheels) {
+            comp.addWheel(wheel.options, wheel.suspension);
+        }
+        return comp;
     }
-    dispose() {
-        var _a;
-        (_a = this.nativeVehicle) === null || _a === void 0 ? void 0 : _a.free();
-        super.dispose();
+    resetMotion() {
+        this.resetSuspension();
+        super.resetMotion();
     }
 }

package/dist/components/rapier-3d-rigid-body.component.d.ts

@@ -1,4 +1,4 @@
-import { Body3DOptions, CollisionEvent, CollisionGroup, DebugBody3DSettings, Entity3d, IRigidBody3dComponent, Point3, Point4, Shape3DDescriptor } from '@gg-web-engine/core';
+import { Body3DOptions, BodyOptions, CollisionEvent, CollisionGroup, DebugBody3DSettings, Entity3d, IRigidBody3dComponent, Point3, Point4, Shape3DDescriptor } from '@gg-web-engine/core';
 import { Collider, ColliderDesc, InteractionGroups, RigidBody, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 import { Observable, Subject } from 'rxjs';
 import { Rapier3dWorldComponent } from './rapier-3d-world.component';
@@ -19,6 +19,25 @@ export declare class Rapier3dRigidBodyComponent implements IRigidBody3dComponent
     get angularVelocity(): Point3;
     set angularVelocity(value: Point3);
     readonly debugBodySettings: DebugBody3DSettings;
+    /**
+     * See `IRigidBodyComponent.bodyOptions`'s own doc. Reads straight off `_bodyDescr`/
+     * `_colliderDescr`/`_colliderOptions` (also what `addToWorld` itself builds the native body/
+     * colliders from, and what `factoryProps`/`clone()` already round-trip) rather than the native
+     * body/colliders - this engine's own API never mutates any of `bodyType`/`mass`/`friction`/
+     * `restitution`/`ccd` after construction, so the stored descriptor is exactly as accurate as a
+     * native query would be.
+     *
+     * `mass` is **not** `_bodyDescr.mass` - unlike `packages/rapier2d`, `Rapier3dFactory.createRigidBodyDescr`
+     * deliberately sets mass on each collider (`ColliderDesc.setMass`), not on the body descriptor
+     * (see that method's own doc for why: a `RigidBodyDesc.mass` is "additional" point mass with no
+     * rotational inertia of its own, wrong for a body whose inertia should scale with its actual
+     * mass). `_bodyDescr.mass` is therefore always its unused default (`0`) regardless of what was
+     * actually requested - the real total is the sum of every collider's own `mass`, which
+     * `ColliderDesc` only carries meaningfully once `setMass`/`setMassProperties` was actually called
+     * on it (true for every collider of a `dynamic` body, per `createRigidBodyDescr`; a `static`/
+     * `kinematic_*` body never calls either, so this correctly sums to `0` for one of those instead).
+     */
+    get bodyOptions(): Readonly<BodyOptions>;
     protected _nativeBody: RigidBody | null;
     protected _nativeBodyColliders: Collider[] | null;
     get nativeBody(): RigidBody | null;
@@ -67,5 +86,8 @@ export declare class Rapier3dRigidBodyComponent implements IRigidBody3dComponent
     addToWorld(world: Rapier3dGgWorld): void;
     removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
     resetMotion(): void;
+    get isSleeping(): boolean;
+    wakeUp(): void;
+    sleep(): void;
     dispose(): void;
 }

package/dist/components/rapier-3d-rigid-body.component.js

@@ -1,6 +1,20 @@
 import { BitMask, DebugBody3DSettings, Pnt3, Qtrn, } from '@gg-web-engine/core';
-import { ColliderDesc, Quaternion, RigidBodyDesc, RigidBodyType, Vector3, } from '@dimforge/rapier3d-compat';
+import { ColliderDesc, MassPropsMode, Quaternion, RigidBodyDesc, RigidBodyType, Vector3, } from '@dimforge/rapier3d-compat';
 import { Subject } from 'rxjs';
+/** Inverse of `Rapier3dFactory.createRigidBodyDescr`'s own `BodyType -> RigidBodyType` mapping -
+ * backs `Rapier3dRigidBodyComponent.bodyOptions`. */
+function rapierBodyTypeToBodyType(status) {
+    switch (status) {
+        case RigidBodyType.Fixed:
+            return 'static';
+        case RigidBodyType.KinematicPositionBased:
+            return 'kinematic_pos';
+        case RigidBodyType.KinematicVelocityBased:
+            return 'kinematic_vel';
+        default:
+            return 'dynamic';
+    }
+}
 export class Rapier3dRigidBodyComponent {
     get position() {
         return Pnt3.clone(this.nativeBody ? this.nativeBody.translation() : this._bodyDescr.translation);
@@ -62,6 +76,35 @@ export class Rapier3dRigidBodyComponent {
             this.nativeBody.setAngvel(new Vector3(value.x, value.y, value.z), true);
         }
     }
+    /**
+     * See `IRigidBodyComponent.bodyOptions`'s own doc. Reads straight off `_bodyDescr`/
+     * `_colliderDescr`/`_colliderOptions` (also what `addToWorld` itself builds the native body/
+     * colliders from, and what `factoryProps`/`clone()` already round-trip) rather than the native
+     * body/colliders - this engine's own API never mutates any of `bodyType`/`mass`/`friction`/
+     * `restitution`/`ccd` after construction, so the stored descriptor is exactly as accurate as a
+     * native query would be.
+     *
+     * `mass` is **not** `_bodyDescr.mass` - unlike `packages/rapier2d`, `Rapier3dFactory.createRigidBodyDescr`
+     * deliberately sets mass on each collider (`ColliderDesc.setMass`), not on the body descriptor
+     * (see that method's own doc for why: a `RigidBodyDesc.mass` is "additional" point mass with no
+     * rotational inertia of its own, wrong for a body whose inertia should scale with its actual
+     * mass). `_bodyDescr.mass` is therefore always its unused default (`0`) regardless of what was
+     * actually requested - the real total is the sum of every collider's own `mass`, which
+     * `ColliderDesc` only carries meaningfully once `setMass`/`setMassProperties` was actually called
+     * on it (true for every collider of a `dynamic` body, per `createRigidBodyDescr`; a `static`/
+     * `kinematic_*` body never calls either, so this correctly sums to `0` for one of those instead).
+     */
+    get bodyOptions() {
+        return {
+            bodyType: rapierBodyTypeToBodyType(this._bodyDescr.status),
+            mass: this._colliderDescr.reduce((sum, cd) => sum + (cd.massPropsMode !== MassPropsMode.Density ? cd.mass : 0), 0),
+            friction: this._colliderOptions.friction,
+            restitution: this._colliderOptions.restitution,
+            ccd: this._bodyDescr.ccdEnabled,
+            ownCollisionGroups: this.ownCollisionGroups,
+            interactWithCollisionGroups: this.interactWithCollisionGroups,
+        };
+    }
     get nativeBody() {
         return this._nativeBody;
     }
@@ -100,7 +143,35 @@ export class Rapier3dRigidBodyComponent {
             const d = new ColliderDesc(cd.shape);
             d.setTranslation(cd.translation.x, cd.translation.y, cd.translation.z);
             d.setRotation(Object.assign({}, cd.rotation));
-            d.setMassProperties(cd.mass, cd.centerOfMass, cd.principalAngularInertia, cd.angularInertiaLocalFrame);
+            // `cd.mass`/`centerOfMass`/`principalAngularInertia`/`angularInertiaLocalFrame` are only
+            // meaningful once something has actually switched `cd` into `MassPropsMode.MassProps` (via
+            // `setMassProperties`) or `.Mass` (via `setMass`/`ColliderDesc.mass`) - otherwise they're just
+            // a freshly-constructed `ColliderDesc`'s zeroed placeholder defaults (confirmed empirically:
+            // `mass: 0`, `principalAngularInertia: {0,0,0}`), irrelevant under the default
+            // `MassPropsMode.Density` mode, which instead derives mass *and* rotational inertia
+            // automatically from the shape and `cd.density`. Unconditionally copying those placeholders via
+            // `setMassProperties` here used to force every `factoryProps`-built collider (every `clone()`,
+            // and - since `Rapier3dRaycastVehicleComponent` builds its own body this same way - every
+            // raycast vehicle chassis) into an explicit zero-mass, zero-rotational-inertia `MassProps` mode
+            // regardless of the original's real mode, silently discarding the shape-derived inertia tensor
+            // a normal `factory.createRigidBody()` body gets for free. The practical symptom this caused:
+            // Rapier's own solver reduces "torque / (zero-plus-epsilon) angular inertia" to no angular
+            // acceleration at all, so a vehicle chassis built this way could never yaw - confirmed
+            // empirically (steering a vehicle chassis produced pure sideways-sliding translation with
+            // `angvel` staying exactly `{0,0,0}` every tick, never even a small nonzero value, which a
+            // merely-large-but-nonzero inertia tensor would still have produced). Fix: only propagate
+            // explicit mass properties when the original was actually in one of those two modes; otherwise
+            // just copy `density` and let Rapier re-derive mass/inertia from the (identical) shape, exactly
+            // like the original was computed.
+            if (cd.massPropsMode === MassPropsMode.MassProps) {
+                d.setMassProperties(cd.mass, cd.centerOfMass, cd.principalAngularInertia, cd.angularInertiaLocalFrame);
+            }
+            else if (cd.massPropsMode === MassPropsMode.Mass) {
+                d.setMass(cd.mass);
+            }
+            else {
+                d.setDensity(cd.density);
+            }
             d.setFriction(cd.friction);
             d.setEnabled(cd.enabled);
             d.setRestitution(cd.restitution);
@@ -128,7 +199,7 @@ export class Rapier3dRigidBodyComponent {
         this.debugBodySettings = new DebugBody3DSettings(this._bodyDescr.status == RigidBodyType.Fixed
             ? { type: 'RIGID_STATIC' }
             : this._bodyDescr.status == RigidBodyType.Dynamic
-                ? { type: 'RIGID_DYNAMIC', sleeping: () => { var _a; return !!((_a = this._nativeBody) === null || _a === void 0 ? void 0 : _a.isSleeping()); } }
+                ? { type: 'RIGID_DYNAMIC', sleeping: () => this.isSleeping }
                 : { type: 'RIGID_KINEMATIC' }, this.shape);
         this._nativeBody = null;
         this._nativeBodyColliders = null;
@@ -242,6 +313,24 @@ export class Rapier3dRigidBodyComponent {
         this._nativeBody.setAngvel(new Vector3(0, 0, 0), false);
         this._nativeBody.setLinvel(new Vector3(0, 0, 0), false);
     }
+    get isSleeping() {
+        var _a;
+        return this._bodyDescr.status !== RigidBodyType.Fixed && !!((_a = this._nativeBody) === null || _a === void 0 ? void 0 : _a.isSleeping());
+    }
+    wakeUp() {
+        var _a;
+        if (this._bodyDescr.status === RigidBodyType.Fixed) {
+            return;
+        }
+        (_a = this._nativeBody) === null || _a === void 0 ? void 0 : _a.wakeUp();
+    }
+    sleep() {
+        var _a;
+        if (this._bodyDescr.status === RigidBodyType.Fixed) {
+            return;
+        }
+        (_a = this._nativeBody) === null || _a === void 0 ? void 0 : _a.sleep();
+    }
     dispose() {
         if (this.nativeBody) {
             this.removeFromWorld({ physicsWorld: this.world }, true);