@gg-web-engine/rapier3d 0.0.72 → 0.0.73

package/dist/components/rapier-3d-trigger.component.js

@@ -54,6 +54,12 @@ export class Rapier3dTriggerComponent extends Rapier3dRigidBodyComponent {
      * component(s) care.
      */
     notifyOverlap(otherBody, started) {
+        // `otherBody` can be a `Rapier3dCharacterControllerComponent` (a player walking through this
+        // trigger) as well as an ordinary rigid body - `onEnter$`/`onLeft$` (and `ITrigger3dComponent`'s
+        // own `onEntityEntered`/`onEntityLeft`) are typed as this same union rather than narrowed to a
+        // rigid body, since a character controller only satisfies `IBodyComponent`, not
+        // `IRigidBodyComponent` (no `linearVelocity`/`resetMotion()`/collision events). This mirrors the
+        // ammo adapter's own `AmmoTriggerComponent`, which resolves the same overlap case the same way.
         if (started) {
             this.overlaps.add(otherBody);
             this.onEnter$.next(otherBody);

package/dist/components/rapier-3d-world.component.d.ts

@@ -2,6 +2,7 @@ import { CollisionGroup, IPhysicsWorld3dComponent, Point3, RaycastOptions, Rayca
 import { Collider, EventQueue, World } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './rapier-3d-rigid-body.component';
 import { Rapier3dCharacterControllerComponent } from './rapier-3d-character-controller.component';
+import { Rapier3dRaycastVehicleComponent } from './rapier-3d-raycast-vehicle.component';
 import { Rapier3dFactory } from '../rapier-3d-factory';
 import { Rapier3dLoader } from '../rapier-3d-loader';
 import { Rapier3dPhysicsTypeDocRepo } from '../types';
@@ -23,7 +24,28 @@ export declare class Rapier3dWorldComponent implements IPhysicsWorld3dComponent<
     get nativeWorld(): World;
     private _eventQueue;
     get eventQueue(): EventQueue;
-    readonly handleIdEntityMap: Map<number, Rapier3dRigidBodyComponent>;
+    /**
+     * Keyed by rigid-body handle. Includes `Rapier3dCharacterControllerComponent`s alongside ordinary
+     * `Rapier3dRigidBodyComponent`s (triggers included, since `Rapier3dTriggerComponent extends
+     * Rapier3dRigidBodyComponent`) - a character controller's kinematic body still gets a real Rapier
+     * rigid-body handle on `addToWorld` (see that class), so it registers here the same way, letting
+     * `dispatchCollisionEvents` resolve sensor-overlap pairs against it (so a `Trigger` fires for a
+     * player walking through it, not just for ordinary rigid bodies/vehicle chassis) and letting
+     * `raycast()` resolve a hit against it too. `dispatchCollisionEvents` still narrows to
+     * `Rapier3dRigidBodyComponent` before treating a pair as a real (non-sensor) contact, since a
+     * character controller has no `notifyCollisionStart`/`notifyCollisionEnd` to call - its physical
+     * response comes from its own sweep-based `move()`, not Rapier's contact solver.
+     */
+    readonly handleIdEntityMap: Map<number, Rapier3dRigidBodyComponent | Rapier3dCharacterControllerComponent>;
+    /**
+     * Every `Rapier3dRaycastVehicleComponent` currently in this world - unlike an ordinary rigid body
+     * or `Rapier3dCharacterControllerComponent`, a vehicle needs an explicit per-tick
+     * `updateVehicle()` call (see that class's own doc for why: nothing steps Rapier's vehicle
+     * controller automatically as part of `World.step()`). `simulate()` drives every registered
+     * vehicle from this set immediately before stepping the world, so the forces it just wrote into
+     * the chassis's velocity get integrated by that same step.
+     */
+    readonly raycastVehicles: Set<Rapier3dRaycastVehicleComponent>;
     constructor();
     init(): Promise<void>;
     simulate(delta: number): void;
@@ -39,6 +61,12 @@ export declare class Rapier3dWorldComponent implements IPhysicsWorld3dComponent<
      * `handleIdEntityMap` is keyed by rigid-body handle (see `addToWorld`), so each handle is resolved
      * via `World.getCollider(handle)` (returns `null` for a since-removed collider, not a throw - safe
      * to just skip) then `Collider.parent()` to reach the owning `RigidBody` before the map lookup.
+     *
+     * `handleIdEntityMap` also holds `Rapier3dCharacterControllerComponent`s (see its own doc), so
+     * `comp1`/`comp2` below can each be a character controller as well as a rigid body/trigger - the
+     * sensor branch handles that directly (`notifyOverlap` accepts either), while the real-contact
+     * branch narrows to `Rapier3dRigidBodyComponent` first, since a character controller has no
+     * collision-event API to call into.
      */
     protected dispatchCollisionEvents(): void;
     /**
@@ -70,6 +98,12 @@ export declare class Rapier3dWorldComponent implements IPhysicsWorld3dComponent<
     protected lockedCollisionGroups: number[];
     registerCollisionGroup(): CollisionGroup;
     deregisterCollisionGroup(group: CollisionGroup): void;
+    /**
+     * `castRay`'s own default (no `filterFlags`) treats a sensor collider as a solid obstacle, exactly
+     * like any real one - `QueryFilterFlags.EXCLUDE_SENSORS` is required so a raycast never reports a
+     * hit against a `Trigger`'s own collider, matching what "trigger" means everywhere else in this
+     * engine (a sensor with no collision response, see `ITrigger3dComponent`).
+     */
     raycast(options: RaycastOptions<Point3>): RaycastResult<Point3, Rapier3dRigidBodyComponent>;
     dispose(): void;
 }

package/dist/components/rapier-3d-world.component.js

@@ -8,7 +8,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { BitMask, Pnt3, } from '@gg-web-engine/core';
-import { EventQueue, init, Vector3, World } from '@dimforge/rapier3d-compat';
+import { EventQueue, init, QueryFilterFlags, Vector3, World } from '@dimforge/rapier3d-compat';
+import { Rapier3dRigidBodyComponent } from './rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './rapier-3d-trigger.component';
 import { Rapier3dFactory } from '../rapier-3d-factory';
 import { Rapier3dLoader } from '../rapier-3d-loader';
@@ -59,7 +60,28 @@ export class Rapier3dWorldComponent {
         this.mainCollisionGroup = 0;
         this._nativeWorld = null;
         this._eventQueue = null;
+        /**
+         * Keyed by rigid-body handle. Includes `Rapier3dCharacterControllerComponent`s alongside ordinary
+         * `Rapier3dRigidBodyComponent`s (triggers included, since `Rapier3dTriggerComponent extends
+         * Rapier3dRigidBodyComponent`) - a character controller's kinematic body still gets a real Rapier
+         * rigid-body handle on `addToWorld` (see that class), so it registers here the same way, letting
+         * `dispatchCollisionEvents` resolve sensor-overlap pairs against it (so a `Trigger` fires for a
+         * player walking through it, not just for ordinary rigid bodies/vehicle chassis) and letting
+         * `raycast()` resolve a hit against it too. `dispatchCollisionEvents` still narrows to
+         * `Rapier3dRigidBodyComponent` before treating a pair as a real (non-sensor) contact, since a
+         * character controller has no `notifyCollisionStart`/`notifyCollisionEnd` to call - its physical
+         * response comes from its own sweep-based `move()`, not Rapier's contact solver.
+         */
         this.handleIdEntityMap = new Map();
+        /**
+         * Every `Rapier3dRaycastVehicleComponent` currently in this world - unlike an ordinary rigid body
+         * or `Rapier3dCharacterControllerComponent`, a vehicle needs an explicit per-tick
+         * `updateVehicle()` call (see that class's own doc for why: nothing steps Rapier's vehicle
+         * controller automatically as part of `World.step()`). `simulate()` drives every registered
+         * vehicle from this set immediately before stepping the world, so the forces it just wrote into
+         * the chassis's velocity get integrated by that same step.
+         */
+        this.raycastVehicles = new Set();
         this.lockedCollisionGroups = [];
         this.added$.subscribe(c => this.children.push(c));
         this.removed$.subscribe(c => this.children.splice(this.children.indexOf(c), 1));
@@ -75,7 +97,14 @@ export class Rapier3dWorldComponent {
     }
     simulate(delta) {
         var _a;
-        this._nativeWorld.timestep = delta / 1000;
+        const dt = delta / 1000;
+        // must run *before* `World.step()` - `updateVehicle` directly writes each vehicle's chassis
+        // velocity from this tick's suspension/engine/brake forces, which `step()` then integrates like
+        // any other dynamic body's velocity (see `Rapier3dRaycastVehicleComponent`'s own doc).
+        for (const vehicle of this.raycastVehicles) {
+            vehicle.stepVehicleController(dt);
+        }
+        this._nativeWorld.timestep = dt;
         (_a = this._nativeWorld) === null || _a === void 0 ? void 0 : _a.step(this.eventQueue);
         this.dispatchCollisionEvents();
     }
@@ -91,6 +120,12 @@ export class Rapier3dWorldComponent {
      * `handleIdEntityMap` is keyed by rigid-body handle (see `addToWorld`), so each handle is resolved
      * via `World.getCollider(handle)` (returns `null` for a since-removed collider, not a throw - safe
      * to just skip) then `Collider.parent()` to reach the owning `RigidBody` before the map lookup.
+     *
+     * `handleIdEntityMap` also holds `Rapier3dCharacterControllerComponent`s (see its own doc), so
+     * `comp1`/`comp2` below can each be a character controller as well as a rigid body/trigger - the
+     * sensor branch handles that directly (`notifyOverlap` accepts either), while the real-contact
+     * branch narrows to `Rapier3dRigidBodyComponent` first, since a character controller has no
+     * collision-event API to call into.
      */
     dispatchCollisionEvents() {
         const nativeWorld = this._nativeWorld;
@@ -122,6 +157,13 @@ export class Rapier3dWorldComponent {
                 }
                 return;
             }
+            // A character controller has no real-contact API (`notifyCollisionStart`/`notifyCollisionEnd`)
+            // to call into - its own sweep-based `move()` already handles physical response, so a non-sensor
+            // pair involving one is simply not reported as a collision event. (Sensor pairs above are
+            // unaffected by this - `notifyOverlap` accepts either component type.)
+            if (!(comp1 instanceof Rapier3dRigidBodyComponent) || !(comp2 instanceof Rapier3dRigidBodyComponent)) {
+                return;
+            }
             if (started) {
                 const geometry = this.computeContactGeometry(collider1, collider2);
                 if (!geometry) {
@@ -219,6 +261,12 @@ export class Rapier3dWorldComponent {
     deregisterCollisionGroup(group) {
         this.lockedCollisionGroups = this.lockedCollisionGroups.filter(x => x !== group);
     }
+    /**
+     * `castRay`'s own default (no `filterFlags`) treats a sensor collider as a solid obstacle, exactly
+     * like any real one - `QueryFilterFlags.EXCLUDE_SENSORS` is required so a raycast never reports a
+     * hit against a `Trigger`'s own collider, matching what "trigger" means everywhere else in this
+     * engine (a sensor with no collision response, see `ITrigger3dComponent`).
+     */
     raycast(options) {
         if (!this._nativeWorld) {
             return { hasHit: false };
@@ -237,7 +285,7 @@ export class Rapier3dWorldComponent {
         const mask = (groups) => {
             return groups ? BitMask.pack(groups, 16) : BitMask.full(16);
         };
-        const hit = this._nativeWorld.castRay(ray, rayLength, true, undefined, (mask(options.collisionFilterGroups) << 16) | mask(options.collisionFilterMask));
+        const hit = this._nativeWorld.castRay(ray, rayLength, true, QueryFilterFlags.EXCLUDE_SENSORS, (mask(options.collisionFilterGroups) << 16) | mask(options.collisionFilterMask));
         if (!hit) {
             return { hasHit: false };
         }
@@ -250,7 +298,14 @@ export class Rapier3dWorldComponent {
             if (!rigidBody) {
                 return { hasHit: false };
             }
-            result.hitBody = this.handleIdEntityMap.get(rigidBody.handle);
+            // `handleIdEntityMap` also holds character controllers now (see its own doc) - raycast's
+            // contract only promises `PTypeDoc['rigidBody'] | PTypeDoc['trigger']`, so a hit against one is
+            // filtered out here rather than surfaced as `hitBody`, unlike a trigger's sensor-overlap
+            // resolution which does report it. `ObjectGrabController`'s character-controller self-hit skip
+            // (see `gg-engine-core-development`) is unaffected either way - it never relied on `hitBody`
+            // resolving at all.
+            const resolvedHitBody = this.handleIdEntityMap.get(rigidBody.handle);
+            result.hitBody = resolvedHitBody instanceof Rapier3dRigidBodyComponent ? resolvedHitBody : undefined;
             result.hitDistance = hit.timeOfImpact;
             result.hitPoint = Pnt3.add(origin, Pnt3.scalarMult(direction, hit.timeOfImpact));
             const rayIntersection = hit.collider.castRayAndGetNormal(ray, hit.timeOfImpact, true);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './components/rapier-3d-rigid-body.component';
 export * from './components/rapier-3d-trigger.component';
+export * from './components/rapier-3d-raycast-vehicle.component';
 export * from './components/rapier-3d-character-controller.component';
 export * from './components/rapier-3d-world.component';
 export * from './rapier-3d-factory';

package/dist/index.js

@@ -1,6 +1,6 @@
 export * from './components/rapier-3d-rigid-body.component';
 export * from './components/rapier-3d-trigger.component';
-// export * from './components/rapier-3d-raycast-vehicle.component';
+export * from './components/rapier-3d-raycast-vehicle.component';
 export * from './components/rapier-3d-character-controller.component';
 export * from './components/rapier-3d-world.component';
 export * from './rapier-3d-factory';

package/dist/rapier-3d-factory.d.ts

@@ -2,6 +2,7 @@ import { Body3DOptions, BodyShape3DDescriptor, CharacterController3dOptions, IPh
 import { ColliderDesc, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './components/rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './components/rapier-3d-trigger.component';
+import { Rapier3dRaycastVehicleComponent } from './components/rapier-3d-raycast-vehicle.component';
 import { Rapier3dCharacterControllerComponent } from './components/rapier-3d-character-controller.component';
 import { Rapier3dWorldComponent } from './components/rapier-3d-world.component';
 import { Rapier3dPhysicsTypeDocRepo } from './types';
@@ -16,7 +17,7 @@ export declare class Rapier3dFactory implements IPhysicsBody3dComponentFactory<R
         position?: Point3;
         rotation?: Point4;
     }): Rapier3dTriggerComponent;
-    createRaycastVehicle(chassis: Rapier3dRigidBodyComponent): never;
+    createRaycastVehicle(chassis: Rapier3dRigidBodyComponent): Rapier3dRaycastVehicleComponent;
     createCharacterController(options: CharacterController3dOptions, transform?: {
         position?: Point3;
         rotation?: Point4;
@@ -25,5 +26,5 @@ export declare class Rapier3dFactory implements IPhysicsBody3dComponentFactory<R
     createRigidBodyDescr(options: Partial<Body3DOptions>, transform?: {
         position?: Point3;
         rotation?: Point4;
-    }): RigidBodyDesc;
+    }, colliderDescr?: ColliderDesc[]): RigidBodyDesc;
 }

package/dist/rapier-3d-factory.js

@@ -2,6 +2,7 @@ import { getCylinderRadii, Pnt3, Qtrn, } from '@gg-web-engine/core';
 import { ActiveEvents, ColliderDesc, Quaternion, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './components/rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './components/rapier-3d-trigger.component';
+import { Rapier3dRaycastVehicleComponent } from './components/rapier-3d-raycast-vehicle.component';
 import { Rapier3dCharacterControllerComponent } from './components/rapier-3d-character-controller.component';
 const DEFAULT_CHARACTER_CONTROLLER_OPTIONS = {
     offset: 0.01,
@@ -14,7 +15,7 @@ const DEFAULT_CHARACTER_CONTROLLER_OPTIONS = {
     interactWithCollisionGroups: 'all',
     // `Rapier3dCharacterControllerComponent.addToWorld` wires this straight into Rapier's own
     // `KinematicCharacterController.setCharacterMass` + `setApplyImpulsesToDynamicBodies(true)` -
-    // unlike the ammo adapter, no hand-rolled push logic needed, Rapier already computes it.
+    // no hand-rolled push logic needed, Rapier already computes it.
     pushMass: 80,
 };
 export class Rapier3dFactory {
@@ -29,7 +30,7 @@ export class Rapier3dFactory {
         // ordinary rigid-body-vs-rigid-body contact needs it here too, since neither side had it before).
         const colliderDescr = this.createColliderDescr(descriptor.shape);
         colliderDescr.forEach(c => c.setActiveEvents(ActiveEvents.COLLISION_EVENTS));
-        return new Rapier3dRigidBodyComponent(this.world, colliderDescr, descriptor.shape, this.createRigidBodyDescr(descriptor.body, transform), Object.assign({ friction: 0.5, restitution: 0.1, ownCollisionGroups: [this.world.mainCollisionGroup], interactWithCollisionGroups: [this.world.mainCollisionGroup], ccd: false }, descriptor.body));
+        return new Rapier3dRigidBodyComponent(this.world, colliderDescr, descriptor.shape, this.createRigidBodyDescr(descriptor.body, transform, colliderDescr), Object.assign({ friction: 0.5, restitution: 0.1, ownCollisionGroups: [this.world.mainCollisionGroup], interactWithCollisionGroups: [this.world.mainCollisionGroup], ccd: false }, descriptor.body));
     }
     createTrigger(descriptor, transform) {
         const colliderDescr = this.createColliderDescr(descriptor);
@@ -40,7 +41,7 @@ export class Rapier3dFactory {
         return new Rapier3dTriggerComponent(this.world, colliderDescr, descriptor, this.createRigidBodyDescr({ bodyType: 'static' }, transform));
     }
     createRaycastVehicle(chassis) {
-        throw new Error('Raycast vehicle bindings for rapier3D are not implemented');
+        return new Rapier3dRaycastVehicleComponent(this.world, chassis);
     }
     createCharacterController(options, transform) {
         const resolvedOptions = Object.assign(Object.assign(Object.assign({}, DEFAULT_CHARACTER_CONTROLLER_OPTIONS), { ownCollisionGroups: [this.world.mainCollisionGroup] }), options);
@@ -127,7 +128,7 @@ export class Rapier3dFactory {
         }
         throw new Error(`Shape "${descriptor.shape}" not implemented for Rapier 3D`);
     }
-    createRigidBodyDescr(options, transform) {
+    createRigidBodyDescr(options, transform, colliderDescr = []) {
         const pos = (transform === null || transform === void 0 ? void 0 : transform.position) || Pnt3.O;
         const rot = (transform === null || transform === void 0 ? void 0 : transform.rotation) || Qtrn.O;
         let bodyDesc;
@@ -143,7 +144,25 @@ export class Rapier3dFactory {
         }
         else {
             bodyDesc = RigidBodyDesc.dynamic();
-            bodyDesc.mass = options.mass || 1;
+            // Mass is set on the collider(s) (`ColliderDesc.setMass`), not as `RigidBodyDesc.mass` -
+            // that field is "additional" mass layered on top of whatever the colliders themselves
+            // contribute (see its own doc: "the total mass of the rigid-body is equal to the sum of this
+            // additional mass and the mass computed from the colliders"), and critically, additional mass
+            // contributes no extra rotational inertia of its own - it behaves like a point mass exactly at
+            // the body's center of mass. Setting it there instead of on the collider(s) used to leave every
+            // dynamic body's rotational inertia derived from the collider's un-scaled default density (1),
+            // regardless of how large `options.mass` actually was - correct enough for the many demos that
+            // never depend on rotational dynamics, but confirmed to visibly break `Rapier3dRaycastVehicleComponent`:
+            // a heavy (mass: 800) chassis with a barely-there (~4kg, density-1-derived) rotational inertia
+            // spun wildly on any steering input (huge angular acceleration for a given torque, since inertia
+            // is what resists it) while still translating at a realistic, correctly-scaled 800kg pace.
+            // `setMass` instead asks Rapier to auto-derive inertia from the shape *scaled to that mass*, the
+            // same computation an un-overridden default density would produce, just correctly sized. Split
+            // evenly across every sub-collider of a `COMPOUND` shape (no per-sub-shape volume query is
+            // exposed to weight this by volume instead) so the sum still equals the requested total mass.
+            const mass = options.mass || 1;
+            const perColliderMass = mass / (colliderDescr.length || 1);
+            colliderDescr.forEach(c => c.setMass(perColliderMass));
             // Only a dynamic body can tunnel through geometry it crosses within a single step - a fixed
             // or kinematic body is never the one doing the moving-too-fast-to-detect part of that, so CCD
             // is meaningless for either (see `BodyOptions.ccd`'s own doc).

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { Rapier3dFactory } from './rapier-3d-factory';
 import { Rapier3dLoader } from './rapier-3d-loader';
 import { Rapier3dRigidBodyComponent } from './components/rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './components/rapier-3d-trigger.component';
+import { Rapier3dRaycastVehicleComponent } from './components/rapier-3d-raycast-vehicle.component';
 import { Rapier3dCharacterControllerComponent } from './components/rapier-3d-character-controller.component';
 import { Gg3dWorld, Gg3dWorldSceneTypeDocPPatch, Gg3dWorldTypeDocPPatch } from '@gg-web-engine/core';
 import { Rapier3dWorldComponent } from './components/rapier-3d-world.component';
@@ -10,7 +11,7 @@ export type Rapier3dPhysicsTypeDocRepo = {
     loader: Rapier3dLoader;
     rigidBody: Rapier3dRigidBodyComponent;
     trigger: Rapier3dTriggerComponent;
-    raycastVehicle: never;
+    raycastVehicle: Rapier3dRaycastVehicleComponent;
     characterController: Rapier3dCharacterControllerComponent;
 };
 export type Rapier3dTypeDoc = Gg3dWorldTypeDocPPatch<Rapier3dPhysicsTypeDocRepo>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gg-web-engine/rapier3d",
-  "version": "0.0.72",
+  "version": "0.0.73",
   "description": "An attempt to create open source game engine for browser",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,7 @@
   "homepage": "https://github.com/AndyGura/gg-web-engine#readme",
   "devDependencies": {
     "@dimforge/rapier3d-compat": "0.20.0",
-    "@gg-web-engine/core": "0.0.72",
+    "@gg-web-engine/core": "0.0.73",
     "@types/jest": "^30.0.0",
     "@types/node": "^26.4.0",
     "jest": "^30.5.0",
@@ -40,7 +40,7 @@
   },
   "peerDependencies": {
     "@dimforge/rapier3d-compat": "0.20.0",
-    "@gg-web-engine/core": "0.0.72",
+    "@gg-web-engine/core": "0.0.73",
     "rxjs": "7.8.2"
   },
   "jest": {

package/test/components/rapier-3d-player-character-controller-integration.spec.ts

@@ -14,6 +14,9 @@ const fakeCamera = () =>
     enableRenderLayer: () => {},
     disableRenderLayer: () => {},
     isRenderLayerEnabled: () => true,
+    // Read once at construction time (`baseFov`) and written back on entering third-person - a
+    // plain field is enough here, this suite doesn't assert on fov itself.
+    camera: { fov: 75 },
   }) as any;
 
 const setup = async () => {

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

@@ -0,0 +1,160 @@
+import { SuspensionOptions, WheelOptions } from '@gg-web-engine/core';
+import { Rapier3dFactory, Rapier3dRaycastVehicleComponent, Rapier3dRigidBodyComponent, Rapier3dWorldComponent } from '../../src';
+
+// Shared suspension/wheel setup mirroring examples/ammo-car-three-rapier3d - see that example
+// for the full car setup.
+const suspension: SuspensionOptions = {
+  compression: 4.4,
+  damping: 2.3,
+  restLength: 0.6,
+  stiffness: 20,
+};
+
+const wheelOptions = (isFront: boolean, isLeft: boolean): WheelOptions => ({
+  isFront,
+  isLeft,
+  tyreRadius: isFront ? 0.35 : 0.4,
+  tyreWidth: isFront ? 0.2 : 0.3,
+  frictionSlip: 1000,
+  rollInfluence: 0.2,
+  maxTravel: 5,
+  position: {
+    x: isLeft ? 1 : -1,
+    y: isFront ? 1.7 : -1,
+    z: 0.3,
+  },
+});
+
+const addWheels = (vehicle: Rapier3dRaycastVehicleComponent) => {
+  for (const isFront of [true, false]) {
+    for (const isLeft of [true, false]) {
+      vehicle.addWheel(wheelOptions(isFront, isLeft), suspension);
+    }
+  }
+};
+
+const createFloor = (factory: Rapier3dFactory, world: Rapier3dWorldComponent, topZ: number): Rapier3dRigidBodyComponent => {
+  const floor = factory.createRigidBody(
+    { shape: { shape: 'BOX', dimensions: { x: 75, y: 75, z: 1 } }, body: { bodyType: 'static', mass: 0 } },
+    { position: { x: 0, y: 0, z: topZ - 0.5 } },
+  );
+  floor.addToWorld({ physicsWorld: world } as any);
+  return floor;
+};
+
+const createVehicle = (
+  world: Rapier3dWorldComponent,
+  factory: Rapier3dFactory,
+  position: { x: number; y: number; z: number },
+): Rapier3dRaycastVehicleComponent => {
+  const chassis = factory.createRigidBody(
+    { shape: { shape: 'BOX', dimensions: { x: 1.8, y: 4, z: 0.6 } }, body: { bodyType: 'dynamic', mass: 800 } },
+    { position },
+  );
+  const vehicle = factory.createRaycastVehicle(chassis);
+  addWheels(vehicle);
+  vehicle.addToWorld({ physicsWorld: world } as any);
+  return vehicle;
+};
+
+// Small steps, matching this package's other integration specs (see
+// `rapier-3d-rigid-body-collision.spec.ts`) rather than one huge `simulate()` call.
+const advance = (world: Rapier3dWorldComponent, totalMs: number, stepMs = 16) => {
+  for (let elapsed = 0; elapsed < totalMs; elapsed += stepMs) {
+    world.simulate(stepMs);
+  }
+};
+
+describe('Rapier3dRaycastVehicleComponent', () => {
+  let world: Rapier3dWorldComponent;
+  let factory: Rapier3dFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new Rapier3dWorldComponent();
+    await world.init();
+    factory = world.factory;
+    // default earth-like gravity, so vehicles actually fall onto the floors below
+    world.gravity = { x: 0, y: 0, z: -9.82 };
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it('should fall under gravity and come to rest on a floor below it', () => {
+    createFloor(factory, world, 0);
+    const vehicle = createVehicle(world, factory, { x: 0, y: 0, z: 4 });
+
+    advance(world, 6000);
+
+    // chassis should have settled just above the floor surface (z = 0), not still falling
+    // and not sunk through it
+    expect(vehicle.position.z).toBeGreaterThan(-1);
+    expect(vehicle.position.z).toBeLessThan(3);
+    expect(vehicle.isWheelTouchesGround(0)).toBe(true);
+  });
+
+  it(
+    'should let each vehicle fall through a floor with a different collision group and rest ' +
+      'only on the floor sharing its own collision group',
+    () => {
+      const groupA = world.registerCollisionGroup();
+      const groupB = world.registerCollisionGroup();
+
+      const floorA = createFloor(factory, world, 0);
+      floorA.ownCollisionGroups = floorA.interactWithCollisionGroups = [groupA];
+
+      const floorB = createFloor(factory, world, -10);
+      floorB.ownCollisionGroups = floorB.interactWithCollisionGroups = [groupB];
+
+      const vehicleA = createVehicle(world, factory, { x: 0, y: 0, z: 4 });
+      vehicleA.ownCollisionGroups = vehicleA.interactWithCollisionGroups = [groupA];
+
+      const vehicleB = createVehicle(world, factory, { x: 20, y: 0, z: 4 });
+      vehicleB.ownCollisionGroups = vehicleB.interactWithCollisionGroups = [groupB];
+
+      advance(world, 6000);
+
+      // vehicleA shares its collision group with floorA (z=0) - it should have landed there, both
+      // via chassis-body collision and via the raycast vehicle's own suspension raycasts.
+      expect(vehicleA.position.z).toBeGreaterThan(-1);
+      expect(vehicleA.position.z).toBeLessThan(3);
+      expect(vehicleA.isWheelTouchesGround(0)).toBe(true);
+
+      // vehicleB does not share a collision group with floorA, so it must fall straight through it
+      // (this is what threading `filterGroups` into `updateVehicle()` fixes - see
+      // `Rapier3dRaycastVehicleComponent.stepVehicleController`'s doc - without it the wheels' own
+      // suspension raycasts would ignore collision groups entirely and detect floorA as ground,
+      // holding the vehicle up even though its chassis passes through). It should come to rest on
+      // floorB (z=-10) instead.
+      expect(vehicleB.position.z).toBeGreaterThan(-11);
+      expect(vehicleB.position.z).toBeLessThan(-7);
+      expect(vehicleB.isWheelTouchesGround(0)).toBe(true);
+    },
+  );
+
+  it('should drive forward under engine force and report a matching positive wheelSpeed', () => {
+    createFloor(factory, world, 0);
+    const vehicle = createVehicle(world, factory, { x: 0, y: 0, z: 2 });
+
+    // let it settle onto the floor first
+    advance(world, 3000);
+    const settledY = vehicle.position.y;
+
+    // apply engine force to the rear wheels (indices 2, 3 per `addWheels`' iteration order)
+    vehicle.applyEngineForce(2, 4000);
+    vehicle.applyEngineForce(3, 4000);
+    advance(world, 3000);
+
+    // the vehicle should have moved forward (+y, this engine's forward axis) and report a
+    // meaningfully positive speed while doing so - not still ~0 and not wildly larger than a sane
+    // few-second driving distance (which would indicate a unit-conversion bug, e.g. a stray x3.6/
+    // /3.6 - see `wheelSpeed`'s own doc).
+    expect(vehicle.position.y).toBeGreaterThan(settledY + 0.5);
+    expect(vehicle.wheelSpeed).toBeGreaterThan(0.1);
+    expect(vehicle.wheelSpeed).toBeLessThan(50);
+  });
+});

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

@@ -0,0 +1,68 @@
+import { Pnt3 } from '@gg-web-engine/core';
+import { Rapier3dFactory, Rapier3dWorldComponent } from '../../src';
+
+describe('Rapier3dRigidBodyComponent.bodyOptions', () => {
+  let world: Rapier3dWorldComponent;
+  let factory: Rapier3dFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new Rapier3dWorldComponent();
+    factory = new Rapier3dFactory(world);
+    await world.init();
+    world.gravity = Pnt3.O;
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it("reads back a dynamic body's mass/friction/restitution/ccd exactly as created", () => {
+    const body = factory.createRigidBody(
+      {
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { bodyType: 'dynamic', mass: 5, friction: 0.3, restitution: 0.7, ccd: true },
+      },
+      { position: { x: 0, y: 0, z: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    expect(body.bodyOptions).toMatchObject({
+      bodyType: 'dynamic',
+      mass: 5,
+      friction: 0.3,
+      restitution: 0.7,
+      ccd: true,
+    });
+  });
+
+  it.each(['static', 'kinematic_pos', 'kinematic_vel'] as const)(
+    'reports bodyType "%s" correctly, with ccd always false for a non-dynamic body',
+    bodyType => {
+      const body = factory.createRigidBody(
+        { shape: { shape: 'SPHERE', radius: 1 }, body: { bodyType, mass: 1, ccd: true } },
+        { position: { x: 0, y: 0, z: 0 } },
+      );
+      body.addToWorld({ physicsWorld: world } as any);
+
+      expect(body.bodyOptions.bodyType).toBe(bodyType);
+      expect(body.bodyOptions.ccd).toBe(false);
+    },
+  );
+
+  it('reflects a mutated ownCollisionGroups/interactWithCollisionGroups live', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'SPHERE', radius: 1 }, body: { bodyType: 'static', mass: 0 } },
+      { position: { x: 0, y: 0, z: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    body.ownCollisionGroups = [3];
+    body.interactWithCollisionGroups = [5, 6];
+
+    expect(body.bodyOptions.ownCollisionGroups).toEqual([3]);
+    expect(body.bodyOptions.interactWithCollisionGroups).toEqual([5, 6]);
+  });
+});