@gg-web-engine/rapier3d 0.0.65 → 0.0.67

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

@@ -1,6 +1,7 @@
 import { CharacterController3dOptions, CollisionGroup, DebugBody3DSettings, Entity3d, ICharacterController3dComponent, 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';
 import { Rapier3dGgWorld, Rapier3dPhysicsTypeDocRepo } from '../types';
 /**
  * A capsule-shaped kinematic character controller backed by Rapier's own `KinematicCharacterController`
@@ -43,6 +44,12 @@ export declare class Rapier3dCharacterControllerComponent implements ICharacterC
     get isGrounded(): boolean;
     private _groundNormal;
     get groundNormal(): Point3 | null;
+    /** See `ICharacterController3dComponent.ignoredBodies`'s doc. Consulted fresh every `move()` call
+     * via `computeColliderMovement`'s own `filterPredicate` - unlike `AmmoCharacterControllerComponent`
+     * (which has to fake this by temporarily pulling ignored bodies out of the collision world),
+     * Rapier's character controller supports excluding specific colliders from a single query
+     * natively, so no such trick is needed here. */
+    readonly ignoredBodies: Set<Rapier3dRigidBodyComponent>;
     private static warnedMissingDtForPush;
     protected _nativeBody: RigidBody | null;
     protected _nativeCollider: Collider | null;
@@ -71,6 +78,14 @@ export declare class Rapier3dCharacterControllerComponent implements ICharacterC
      * needed here.
      */
     private syncColliderTransform;
+    /**
+     * Builds `computeColliderMovement`'s `filterPredicate` from `ignoredBodies` - `undefined` when
+     * empty (the common case) rather than an always-true closure, so an empty `ignoredBodies` set costs
+     * nothing extra per query. Compares by `RigidBody.handle` (a plain numeric id), not object
+     * identity - `Collider.parent()` isn't guaranteed to return the same wrapper instance across calls
+     * for the pinned `@dimforge/rapier3d-compat` build, only the same underlying native body.
+     */
+    private ignoredBodiesFilterPredicate;
     move(desiredTranslation: Point3, dt?: number): void;
     /**
      * Shoves any dynamic body this tick's sweep bumped into - see `addToWorld`'s doc for why this is

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

@@ -112,6 +112,12 @@ export class Rapier3dCharacterControllerComponent {
         this.name = '';
         this._isGrounded = false;
         this._groundNormal = null;
+        /** See `ICharacterController3dComponent.ignoredBodies`'s doc. Consulted fresh every `move()` call
+         * via `computeColliderMovement`'s own `filterPredicate` - unlike `AmmoCharacterControllerComponent`
+         * (which has to fake this by temporarily pulling ignored bodies out of the collision world),
+         * Rapier's character controller supports excluding specific colliders from a single query
+         * natively, so no such trick is needed here. */
+        this.ignoredBodies = new Set();
         this._nativeBody = null;
         this._nativeCollider = null;
         this._nativeController = null;
@@ -135,6 +141,31 @@ export class Rapier3dCharacterControllerComponent {
     syncColliderTransform() {
         this.world.nativeWorld.propagateModifiedBodyPositionsToColliders();
     }
+    /**
+     * Builds `computeColliderMovement`'s `filterPredicate` from `ignoredBodies` - `undefined` when
+     * empty (the common case) rather than an always-true closure, so an empty `ignoredBodies` set costs
+     * nothing extra per query. Compares by `RigidBody.handle` (a plain numeric id), not object
+     * identity - `Collider.parent()` isn't guaranteed to return the same wrapper instance across calls
+     * for the pinned `@dimforge/rapier3d-compat` build, only the same underlying native body.
+     */
+    ignoredBodiesFilterPredicate() {
+        if (this.ignoredBodies.size === 0) {
+            return undefined;
+        }
+        const ignoredHandles = new Set();
+        for (const body of this.ignoredBodies) {
+            if (body.nativeBody) {
+                ignoredHandles.add(body.nativeBody.handle);
+            }
+        }
+        if (ignoredHandles.size === 0) {
+            return undefined;
+        }
+        return (collider) => {
+            const parent = collider.parent();
+            return !parent || !ignoredHandles.has(parent.handle);
+        };
+    }
     move(desiredTranslation, dt) {
         if (!this._nativeBody || !this._nativeCollider || !this._nativeController) {
             // not yet added to the world - nothing to sweep against (matches
@@ -180,7 +211,7 @@ export class Rapier3dCharacterControllerComponent {
             }
         }
         const desired = new Vector3(desiredTranslation.x, desiredTranslation.y, desiredTranslation.z);
-        this._nativeController.computeColliderMovement(this._nativeCollider, desired);
+        this._nativeController.computeColliderMovement(this._nativeCollider, desired, undefined, 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);

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

@@ -1,5 +1,6 @@
-import { Body3DOptions, CollisionGroup, DebugBody3DSettings, Entity3d, IRigidBody3dComponent, Point3, Point4, Shape3DDescriptor } from '@gg-web-engine/core';
+import { Body3DOptions, 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';
 import { Rapier3dGgWorld, Rapier3dPhysicsTypeDocRepo } from '../types';
 export declare class Rapier3dRigidBodyComponent implements IRigidBody3dComponent<Rapier3dPhysicsTypeDocRepo> {
@@ -23,6 +24,33 @@ export declare class Rapier3dRigidBodyComponent implements IRigidBody3dComponent
     get nativeBody(): RigidBody | null;
     set nativeBody(value: RigidBody | null);
     name: string;
+    /**
+     * Other rigid-body components this one is currently touching via a real (non-sensor) contact -
+     * mirrors `Rapier3dTriggerComponent.overlaps`, but symmetric: both sides of an ordinary collision
+     * get notified, so both sides track it. Populated/drained by `Rapier3dWorldComponent`'s centralized
+     * collision-event dispatch (see `notifyCollisionStart`/`notifyCollisionEnd` below), and consulted by
+     * `removeFromWorld` to emit `onCollisionEnd(null)` to any partner still touching this body at the
+     * moment it's removed (per `CollisionEvent`'s "null when the other body was removed from the world
+     * while still in contact" convention) - Rapier does not reliably emit a native collision-stop event
+     * for a collider that's simply deleted mid-contact (same reason `Rapier3dTriggerComponent.
+     * checkOverlaps` has its own manual `!body.nativeBody` cleanup pass instead of trusting the event
+     * queue for that case).
+     */
+    readonly collidingWith: Set<Rapier3dRigidBodyComponent>;
+    protected readonly onCollisionStart$: Subject<CollisionEvent<Point3, Rapier3dRigidBodyComponent>>;
+    protected readonly onCollisionEnd$: Subject<Rapier3dRigidBodyComponent | null>;
+    get onCollisionStart(): Observable<CollisionEvent<Point3, Rapier3dRigidBodyComponent>>;
+    get onCollisionEnd(): Observable<Rapier3dRigidBodyComponent | null>;
+    /**
+     * Called by `Rapier3dWorldComponent`'s centralized collision-event dispatch (see
+     * `Rapier3dWorldComponent.simulate`) - not meant to be called by app code directly. Kept `public`
+     * (rather than some cross-class-accessible `protected`) purely because the dispatching class isn't
+     * a subclass of this one; there's nothing else in this package it's meant to be called from.
+     */
+    notifyCollisionStart(event: CollisionEvent<Point3, Rapier3dRigidBodyComponent>): void;
+    /** See `notifyCollisionStart`'s doc. `otherBody: null` signals the partner was removed from the
+     *  world while still in contact, per `onCollisionEnd`'s doc. */
+    notifyCollisionEnd(otherBody: Rapier3dRigidBodyComponent | null): void;
     get factoryProps(): [
         ColliderDesc[],
         Shape3DDescriptor,

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

@@ -1,12 +1,13 @@
 import { BitMask, DebugBody3DSettings, Pnt3, Qtrn, } from '@gg-web-engine/core';
 import { ColliderDesc, Quaternion, RigidBodyDesc, Vector3, } from '@dimforge/rapier3d-compat';
+import { Subject } from 'rxjs';
 export class Rapier3dRigidBodyComponent {
     get position() {
         return Pnt3.clone(this.nativeBody ? this.nativeBody.translation() : this._bodyDescr.translation);
     }
     set position(value) {
         if (this.nativeBody) {
-            this.nativeBody.setTranslation(new Vector3(value.x, value.y, value.z), false);
+            this.nativeBody.setTranslation(new Vector3(value.x, value.y, value.z), true);
         }
         else {
             this._bodyDescr.setTranslation(value.x, value.y, value.z);
@@ -17,7 +18,7 @@ export class Rapier3dRigidBodyComponent {
     }
     set rotation(value) {
         if (this.nativeBody) {
-            this.nativeBody.setRotation(new Quaternion(value.x, value.y, value.z, value.w), false);
+            this.nativeBody.setRotation(new Quaternion(value.x, value.y, value.z, value.w), true);
         }
         else {
             this._bodyDescr.setRotation(new Quaternion(value.x, value.y, value.z, value.w));
@@ -29,7 +30,8 @@ export class Rapier3dRigidBodyComponent {
     }
     set linearVelocity(value) {
         if (this.nativeBody) {
-            this.nativeBody.setLinvel(new Vector3(value.x, value.y, value.z), false);
+            // see `position`'s setter above for why `true` (wake up) is required
+            this.nativeBody.setLinvel(new Vector3(value.x, value.y, value.z), true);
         }
     }
     get angularVelocity() {
@@ -38,7 +40,8 @@ export class Rapier3dRigidBodyComponent {
     }
     set angularVelocity(value) {
         if (this.nativeBody) {
-            this.nativeBody.setAngvel(new Vector3(value.x, value.y, value.z), false);
+            // see `position`'s setter above for why `true` (wake up) is required
+            this.nativeBody.setAngvel(new Vector3(value.x, value.y, value.z), true);
         }
     }
     get nativeBody() {
@@ -50,6 +53,30 @@ export class Rapier3dRigidBodyComponent {
         }
         this._nativeBody = value;
     }
+    get onCollisionStart() {
+        return this.onCollisionStart$.asObservable();
+    }
+    get onCollisionEnd() {
+        return this.onCollisionEnd$.asObservable();
+    }
+    /**
+     * Called by `Rapier3dWorldComponent`'s centralized collision-event dispatch (see
+     * `Rapier3dWorldComponent.simulate`) - not meant to be called by app code directly. Kept `public`
+     * (rather than some cross-class-accessible `protected`) purely because the dispatching class isn't
+     * a subclass of this one; there's nothing else in this package it's meant to be called from.
+     */
+    notifyCollisionStart(event) {
+        this.collidingWith.add(event.otherBody);
+        this.onCollisionStart$.next(event);
+    }
+    /** See `notifyCollisionStart`'s doc. `otherBody: null` signals the partner was removed from the
+     *  world while still in contact, per `onCollisionEnd`'s doc. */
+    notifyCollisionEnd(otherBody) {
+        if (otherBody) {
+            this.collidingWith.delete(otherBody);
+        }
+        this.onCollisionEnd$.next(otherBody);
+    }
     get factoryProps() {
         const colliderDescr = this._colliderDescr.map(cd => {
             const d = new ColliderDesc(cd.shape);
@@ -82,6 +109,21 @@ export class Rapier3dRigidBodyComponent {
         this._nativeBody = null;
         this._nativeBodyColliders = null;
         this.name = '';
+        /**
+         * Other rigid-body components this one is currently touching via a real (non-sensor) contact -
+         * mirrors `Rapier3dTriggerComponent.overlaps`, but symmetric: both sides of an ordinary collision
+         * get notified, so both sides track it. Populated/drained by `Rapier3dWorldComponent`'s centralized
+         * collision-event dispatch (see `notifyCollisionStart`/`notifyCollisionEnd` below), and consulted by
+         * `removeFromWorld` to emit `onCollisionEnd(null)` to any partner still touching this body at the
+         * moment it's removed (per `CollisionEvent`'s "null when the other body was removed from the world
+         * while still in contact" convention) - Rapier does not reliably emit a native collision-stop event
+         * for a collider that's simply deleted mid-contact (same reason `Rapier3dTriggerComponent.
+         * checkOverlaps` has its own manual `!body.nativeBody` cleanup pass instead of trusting the event
+         * queue for that case).
+         */
+        this.collidingWith = new Set();
+        this.onCollisionStart$ = new Subject();
+        this.onCollisionEnd$ = new Subject();
         this.collisionGroups = BitMask.full(32);
         this.ownCollisionGroups = (_colliderOptions === null || _colliderOptions === void 0 ? void 0 : _colliderOptions.ownCollisionGroups) || [world.mainCollisionGroup];
         this.interactWithCollisionGroups = (_colliderOptions === null || _colliderOptions === void 0 ? void 0 : _colliderOptions.interactWithCollisionGroups) || [world.mainCollisionGroup];
@@ -154,6 +196,13 @@ export class Rapier3dRigidBodyComponent {
         if (world.physicsWorld != this.world) {
             throw new Error('Rapier3D bodies cannot be shared between different worlds');
         }
+        // notify every body still touching this one that the contact ended because *this* body vanished
+        // (not because they physically separated) - see `collidingWith`'s doc.
+        for (const other of this.collidingWith) {
+            other.collidingWith.delete(this);
+            other.notifyCollisionEnd(null);
+        }
+        this.collidingWith.clear();
         if (this._nativeBody) {
             for (const col of this._nativeBodyColliders) {
                 this.world.nativeWorld.removeCollider(col, false);
@@ -173,5 +222,7 @@ export class Rapier3dRigidBodyComponent {
         if (this.nativeBody) {
             this.removeFromWorld({ physicsWorld: this.world }, true);
         }
+        this.onCollisionStart$.complete();
+        this.onCollisionEnd$.complete();
     }
 }

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

@@ -18,7 +18,28 @@ export declare class Rapier3dTriggerComponent extends Rapier3dRigidBodyComponent
     constructor(world: Rapier3dWorldComponent, _colliderDescr: ColliderDesc[], shape: Shape3DDescriptor, _bodyDescr: RigidBodyDesc);
     addToWorld(world: Rapier3dGgWorld): void;
     removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
+    /**
+     * Called by `Rapier3dWorldComponent`'s centralized collision-event dispatch (see
+     * `Rapier3dWorldComponent.simulate`) once per drained sensor-intersection event involving this
+     * trigger - not meant to be called by app code directly. Previously this trigger drained
+     * `world.eventQueue` itself from inside `checkOverlaps()`, matching `otherBody` by comparing an
+     * event's *collider* handle against `this.nativeBody?.handle` (a *rigid-body* handle) - those are
+     * two different handle namespaces in this pinned `@dimforge/rapier3d-compat` build, and the
+     * comparison only ever happened to work by coincidence (a body's first/only collider is allocated
+     * from a separate arena that, absent any prior removals, marches in lockstep with the rigid-body
+     * arena for the common one-collider-per-body case - see `gg-engine-physics-adapter-rapier` for the
+     * full incident). `EventQueue.drainCollisionEvents` also fully drains the *shared* queue on every
+     * call, so more than one consumer draining it independently (this trigger, another trigger, and now
+     * `Rapier3dRigidBodyComponent`'s own collision events) would silently steal each other's events -
+     * `Rapier3dWorldComponent` is now the single place that drains it, resolving collider handles to
+     * components correctly via `Collider.parent()`, and pushes matching events to whichever
+     * component(s) care.
+     */
+    notifyOverlap(otherBody: Rapier3dRigidBodyComponent, started: boolean): void;
     checkOverlaps(): void;
     clone(): Rapier3dTriggerComponent;
+    /** Completes `onEnter$`/`onLeft$` on top of `Rapier3dRigidBodyComponent.dispose()`'s own
+     * `onCollisionStart$`/`onCollisionEnd$` completion (via `super.dispose()`) - this trigger's own
+     * subjects have no other owner to complete them. */
     dispose(): void;
 }

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

@@ -36,27 +36,38 @@ export class Rapier3dTriggerComponent extends Rapier3dRigidBodyComponent {
         this.overlaps.clear();
         super.removeFromWorld(world, dispose);
     }
+    /**
+     * Called by `Rapier3dWorldComponent`'s centralized collision-event dispatch (see
+     * `Rapier3dWorldComponent.simulate`) once per drained sensor-intersection event involving this
+     * trigger - not meant to be called by app code directly. Previously this trigger drained
+     * `world.eventQueue` itself from inside `checkOverlaps()`, matching `otherBody` by comparing an
+     * event's *collider* handle against `this.nativeBody?.handle` (a *rigid-body* handle) - those are
+     * two different handle namespaces in this pinned `@dimforge/rapier3d-compat` build, and the
+     * comparison only ever happened to work by coincidence (a body's first/only collider is allocated
+     * from a separate arena that, absent any prior removals, marches in lockstep with the rigid-body
+     * arena for the common one-collider-per-body case - see `gg-engine-physics-adapter-rapier` for the
+     * full incident). `EventQueue.drainCollisionEvents` also fully drains the *shared* queue on every
+     * call, so more than one consumer draining it independently (this trigger, another trigger, and now
+     * `Rapier3dRigidBodyComponent`'s own collision events) would silently steal each other's events -
+     * `Rapier3dWorldComponent` is now the single place that drains it, resolving collider handles to
+     * components correctly via `Collider.parent()`, and pushes matching events to whichever
+     * component(s) care.
+     */
+    notifyOverlap(otherBody, started) {
+        if (started) {
+            this.overlaps.add(otherBody);
+            this.onEnter$.next(otherBody);
+        }
+        else {
+            this.overlaps.delete(otherBody);
+            this.onLeft$.next(otherBody);
+        }
+    }
     checkOverlaps() {
-        this.world.eventQueue.drainCollisionEvents((h1, h2, started) => {
-            var _a, _b;
-            let otherBody;
-            if (h1 === ((_a = this.nativeBody) === null || _a === void 0 ? void 0 : _a.handle)) {
-                otherBody = this.world.handleIdEntityMap.get(h2);
-            }
-            else if (h2 === ((_b = this.nativeBody) === null || _b === void 0 ? void 0 : _b.handle)) {
-                otherBody = this.world.handleIdEntityMap.get(h1);
-            }
-            if (!otherBody)
-                return;
-            if (started) {
-                this.overlaps.add(otherBody);
-                this.onEnter$.next(otherBody);
-            }
-            else {
-                this.overlaps.delete(otherBody);
-                this.onLeft$.next(otherBody);
-            }
-        });
+        // Rapier does not reliably emit a native intersection-stop event for a collider that's simply
+        // removed from the world mid-overlap (confirmed empirically) - this manual pass catches that case
+        // every tick regardless of whether `Rapier3dWorldComponent.simulate`'s own event dispatch already
+        // ran this tick.
         for (const body of this.overlaps.keys()) {
             if (!body.nativeBody) {
                 this.overlaps.delete(body);
@@ -71,8 +82,13 @@ export class Rapier3dTriggerComponent extends Rapier3dRigidBodyComponent {
         component.interactWithCollisionGroups = this.interactWithCollisionGroups;
         return component;
     }
+    /** Completes `onEnter$`/`onLeft$` on top of `Rapier3dRigidBodyComponent.dispose()`'s own
+     * `onCollisionStart$`/`onCollisionEnd$` completion (via `super.dispose()`) - this trigger's own
+     * subjects have no other owner to complete them. */
     dispose() {
         this.overlaps.clear();
+        this.onEnter$.complete();
+        this.onLeft$.complete();
         super.dispose();
     }
 }

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

@@ -1,5 +1,5 @@
 import { CollisionGroup, IPhysicsWorld3dComponent, Point3, RaycastOptions, RaycastResult } from '@gg-web-engine/core';
-import { EventQueue, World } from '@dimforge/rapier3d-compat';
+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 { Rapier3dFactory } from '../rapier-3d-factory';
@@ -27,6 +27,46 @@ export declare class Rapier3dWorldComponent implements IPhysicsWorld3dComponent<
     constructor();
     init(): Promise<void>;
     simulate(delta: number): void;
+    /**
+     * Drains `eventQueue` exactly once per `simulate()` call and routes each entry to whichever
+     * component(s) care - this is the *only* place `drainCollisionEvents` is called for the whole
+     * world (see `Rapier3dTriggerComponent.notifyOverlap`'s doc for why a second/independent drain
+     * elsewhere would silently steal events from this one). A collider pair with sensor
+     * semantics (either side `isSensor()`) is routed as a trigger overlap; an ordinary pair is routed
+     * as a real rigid-body collision.
+     *
+     * `EventQueue.drainCollisionEvents` reports *collider* handles, not rigid-body handles -
+     * `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.
+     */
+    protected dispatchCollisionEvents(): void;
+    /**
+     * Reads world-space contact position/normal/impulse for a just-started contact between two
+     * non-sensor colliders via `World.contactPair`'s `TempContactManifold`. Returns `null` only if the
+     * pair has no manifold at all (shouldn't normally happen for a pair `drainCollisionEvents` just
+     * reported as newly touching, but guarded defensively). `World.contactPair`'s callback can in
+     * principle be invoked once per manifold between the pair - for the compound/multi-collider shapes
+     * this can matter for, each sub-collider pair already gets its own separate `drainCollisionEvents`
+     * entry (and thus its own `computeContactGeometry` call) since collision events are per-*collider*,
+     * not per-body, so in practice a single call here only ever sees one manifold; only the first
+     * encountered is used regardless. `impulse` sums `contactImpulse(i)` across every contact point of
+     * that manifold (an already-solved *impulse*, not a force estimate - the pinned
+     * `@dimforge/rapier3d-compat` build's constraint solver runs within the same `World.step()` call
+     * that produced this `started` event, so the manifold's impulses are already up to date by the time
+     * this runs). `normal` is returned oriented "away from `collider1` towards `collider2`" - Rapier's
+     * `contactPair(a, b, f)` reports whether its own internally-cached manifold order matches the
+     * queried `(a, b)` order via the callback's `flipped` flag; when `flipped` is `true` the manifold's
+     * `normal()` (always world-space, always pointing from the manifold's own shape1 to shape2) actually
+     * points from `collider2` to `collider1` and must be negated to match this method's documented
+     * orientation - verified empirically against a ball resting on a floor below it (see
+     * `gg-engine-physics-adapter-rapier` for the exact reproduction).
+     */
+    protected computeContactGeometry(collider1: Collider, collider2: Collider): {
+        position: Point3;
+        normal: Point3;
+        impulse: number;
+    } | null;
     protected lockedCollisionGroups: number[];
     registerCollisionGroup(): CollisionGroup;
     deregisterCollisionGroup(group: CollisionGroup): void;

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

@@ -9,6 +9,7 @@ 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 { Rapier3dTriggerComponent } from './rapier-3d-trigger.component';
 import { Rapier3dFactory } from '../rapier-3d-factory';
 import { Rapier3dLoader } from '../rapier-3d-loader';
 import { Subject } from 'rxjs';
@@ -76,6 +77,135 @@ export class Rapier3dWorldComponent {
         var _a;
         this._nativeWorld.timestep = delta / 1000;
         (_a = this._nativeWorld) === null || _a === void 0 ? void 0 : _a.step(this.eventQueue);
+        this.dispatchCollisionEvents();
+    }
+    /**
+     * Drains `eventQueue` exactly once per `simulate()` call and routes each entry to whichever
+     * component(s) care - this is the *only* place `drainCollisionEvents` is called for the whole
+     * world (see `Rapier3dTriggerComponent.notifyOverlap`'s doc for why a second/independent drain
+     * elsewhere would silently steal events from this one). A collider pair with sensor
+     * semantics (either side `isSensor()`) is routed as a trigger overlap; an ordinary pair is routed
+     * as a real rigid-body collision.
+     *
+     * `EventQueue.drainCollisionEvents` reports *collider* handles, not rigid-body handles -
+     * `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.
+     */
+    dispatchCollisionEvents() {
+        const nativeWorld = this._nativeWorld;
+        if (!nativeWorld) {
+            return;
+        }
+        this.eventQueue.drainCollisionEvents((h1, h2, started) => {
+            const collider1 = nativeWorld.getCollider(h1);
+            const collider2 = nativeWorld.getCollider(h2);
+            if (!collider1 || !collider2) {
+                return;
+            }
+            const body1 = collider1.parent();
+            const body2 = collider2.parent();
+            if (!body1 || !body2) {
+                return;
+            }
+            const comp1 = this.handleIdEntityMap.get(body1.handle);
+            const comp2 = this.handleIdEntityMap.get(body2.handle);
+            if (!comp1 || !comp2 || comp1 === comp2) {
+                return;
+            }
+            if (collider1.isSensor() || collider2.isSensor()) {
+                if (comp1 instanceof Rapier3dTriggerComponent) {
+                    comp1.notifyOverlap(comp2, started);
+                }
+                if (comp2 instanceof Rapier3dTriggerComponent) {
+                    comp2.notifyOverlap(comp1, started);
+                }
+                return;
+            }
+            if (started) {
+                const geometry = this.computeContactGeometry(collider1, collider2);
+                if (!geometry) {
+                    return;
+                }
+                const v1 = body1.linvel();
+                const v2 = body2.linvel();
+                comp1.notifyCollisionStart({
+                    otherBody: comp2,
+                    position: geometry.position,
+                    normal: geometry.normal,
+                    relativeVelocity: Pnt3.sub(v2, v1),
+                    impulse: geometry.impulse,
+                });
+                comp2.notifyCollisionStart({
+                    otherBody: comp1,
+                    position: geometry.position,
+                    normal: Pnt3.scalarMult(geometry.normal, -1),
+                    relativeVelocity: Pnt3.sub(v1, v2),
+                    impulse: geometry.impulse,
+                });
+            }
+            else {
+                comp1.notifyCollisionEnd(comp2);
+                comp2.notifyCollisionEnd(comp1);
+            }
+        });
+    }
+    /**
+     * Reads world-space contact position/normal/impulse for a just-started contact between two
+     * non-sensor colliders via `World.contactPair`'s `TempContactManifold`. Returns `null` only if the
+     * pair has no manifold at all (shouldn't normally happen for a pair `drainCollisionEvents` just
+     * reported as newly touching, but guarded defensively). `World.contactPair`'s callback can in
+     * principle be invoked once per manifold between the pair - for the compound/multi-collider shapes
+     * this can matter for, each sub-collider pair already gets its own separate `drainCollisionEvents`
+     * entry (and thus its own `computeContactGeometry` call) since collision events are per-*collider*,
+     * not per-body, so in practice a single call here only ever sees one manifold; only the first
+     * encountered is used regardless. `impulse` sums `contactImpulse(i)` across every contact point of
+     * that manifold (an already-solved *impulse*, not a force estimate - the pinned
+     * `@dimforge/rapier3d-compat` build's constraint solver runs within the same `World.step()` call
+     * that produced this `started` event, so the manifold's impulses are already up to date by the time
+     * this runs). `normal` is returned oriented "away from `collider1` towards `collider2`" - Rapier's
+     * `contactPair(a, b, f)` reports whether its own internally-cached manifold order matches the
+     * queried `(a, b)` order via the callback's `flipped` flag; when `flipped` is `true` the manifold's
+     * `normal()` (always world-space, always pointing from the manifold's own shape1 to shape2) actually
+     * points from `collider2` to `collider1` and must be negated to match this method's documented
+     * orientation - verified empirically against a ball resting on a floor below it (see
+     * `gg-engine-physics-adapter-rapier` for the exact reproduction).
+     */
+    computeContactGeometry(collider1, collider2) {
+        const nativeWorld = this._nativeWorld;
+        if (!nativeWorld) {
+            return null;
+        }
+        let result = null;
+        nativeWorld.contactPair(collider1, collider2, (manifold, flipped) => {
+            if (result) {
+                // only the first manifold is used - see doc above.
+                return;
+            }
+            const rawNormal = manifold.normal();
+            const normal = flipped
+                ? { x: -rawNormal.x, y: -rawNormal.y, z: -rawNormal.z }
+                : { x: rawNormal.x, y: rawNormal.y, z: rawNormal.z };
+            const numSolverContacts = manifold.numSolverContacts();
+            let position = Pnt3.O;
+            if (numSolverContacts > 0) {
+                let sum = Pnt3.O;
+                for (let i = 0; i < numSolverContacts; i++) {
+                    const p = manifold.solverContactPoint(i);
+                    if (p) {
+                        sum = Pnt3.add(sum, p);
+                    }
+                }
+                position = Pnt3.scalarMult(sum, 1 / numSolverContacts);
+            }
+            let impulse = 0;
+            const numContacts = manifold.numContacts();
+            for (let i = 0; i < numContacts; i++) {
+                impulse += manifold.contactImpulse(i);
+            }
+            result = { position, normal, impulse };
+        });
+        return result;
     }
     registerCollisionGroup() {
         for (let i = 1; i < 16; i++) {

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

@@ -22,7 +22,14 @@ export class Rapier3dFactory {
         this.world = world;
     }
     createRigidBody(descriptor, transform) {
-        return new Rapier3dRigidBodyComponent(this.world, this.createColliderDescr(descriptor.shape), descriptor.shape, this.createRigidBodyDescr(descriptor.body, transform), Object.assign({ friction: 0.5, restitution: 0.1, ownCollisionGroups: [this.world.mainCollisionGroup], interactWithCollisionGroups: [this.world.mainCollisionGroup] }, descriptor.body));
+        // `Rapier3dRigidBodyComponent.onCollisionStart`/`onCollisionEnd` are backed by Rapier's own
+        // collision-event queue (drained centrally by `Rapier3dWorldComponent.simulate`), which only
+        // reports a contact pair when *at least one* of its two colliders has `COLLISION_EVENTS` active
+        // (triggers already set this on their own sensor collider - see `createTrigger` below - but an
+        // 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] }, descriptor.body));
     }
     createTrigger(descriptor, transform) {
         const colliderDescr = this.createColliderDescr(descriptor);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@gg-web-engine/rapier3d",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "description": "An attempt to create open source game engine for browser",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "test": "jest",
-    "prettier-format": "prettier --config ../core/.prettierrc 'src/**/*.ts' --write",
+    "prettier-format": "prettier --config ../../.prettierrc 'src/**/*.ts' --write",
     "prepublish": "rm -rf ./dist/ && tsc",
     "build": "tsc"
   },
@@ -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.65",
+    "@gg-web-engine/core": "0.0.67",
     "@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.65",
+    "@gg-web-engine/core": "0.0.67",
     "rxjs": "7.8.2"
   },
   "jest": {

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

@@ -144,6 +144,46 @@ describe('Rapier3dCharacterControllerComponent', () => {
     expect(character.isGrounded).toBe(true);
   });
 
+  it(
+    'walks straight through a body added to ignoredBodies instead of sliding to a stop against it ' +
+      "(regression: collision groups alone can't express excluding just one specific body while both " +
+      'it and the character still need to collide with the rest of the world - see ' +
+      '`ICharacterController3dComponent.ignoredBodies`\'s doc)',
+    () => {
+      addFloor(0, 20, 0);
+      const wall = addWall(2);
+      const character = factory.createCharacterController(CHAR_OPTIONS, {
+        position: { x: 0, y: 0, z: HALF_HEIGHT + 0.5 },
+      });
+      character.addToWorld({ physicsWorld: world } as any);
+      character.ignoredBodies.add(wall);
+      settleWorld();
+      character.move({ x: 0, y: 0, z: -1 });
+
+      character.move({ x: 5, y: 0, z: 0 });
+
+      // unlike the baseline test above, nothing stopped it short of the wall's x=2 near face
+      expect(character.position.x).toBeCloseTo(5);
+    },
+  );
+
+  it('removing a body from ignoredBodies makes it block the character again', () => {
+    addFloor(0, 20, 0);
+    const wall = addWall(2);
+    const character = factory.createCharacterController(CHAR_OPTIONS, {
+      position: { x: 0, y: 0, z: HALF_HEIGHT + 0.5 },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    character.ignoredBodies.add(wall);
+    character.ignoredBodies.delete(wall);
+    settleWorld();
+    character.move({ x: 0, y: 0, z: -1 });
+
+    character.move({ x: 5, y: 0, z: 0 });
+
+    expect(character.position.x).toBeLessThan(1.6);
+  });
+
   it('should step up a ledge shorter than maxStepHeight without getting stuck', () => {
     const maxStepHeight = 0.3;
     const stepZ = 0.2; // below maxStepHeight

package/test/components/rapier-3d-object-grab-integration.spec.ts

@@ -0,0 +1,147 @@
+import {
+  CharacterController3dEntity,
+  Grabbable3dEntity,
+  KeyboardInput,
+  MouseInput,
+  ObjectGrabController,
+  Pnt3,
+  Point3,
+  Qtrn,
+} from '@gg-web-engine/core';
+import { Rapier3dWorldComponent } from '../../src';
+
+/**
+ * Regression coverage for the Rapier3d-specific counterpart of
+ * `packages/ammo/test/components/ammo-world.component.spec.ts`'s "should still grab a small target
+ * sitting closer than the ray origin overshoots to" test - both reproduce the same real scene (the
+ * `portal-room` example's pedestal + radio prop), but they can't share a test body: the two adapters
+ * were broken by, and fixed for, two different bugs at two different layers.
+ *
+ * Ammo's gap lived in `AmmoWorldComponent.raycast()` itself - Bullet's plain `rayTest` can't detect a
+ * shape already containing the ray's origin at all, so a ray landing *inside* the small prop found
+ * nothing until the adapter grew its own `solidRayFallback`. Rapier never had that gap -
+ * `Rapier3dWorldComponent.raycast()`'s `castRay(..., solid: true, ...)` already reports a distance-`0`
+ * hit for whatever shape contains the ray's origin, prop included, with no adapter-level fix needed.
+ *
+ * Rapier's bug was one level up, in `ObjectGrabController.tryGrab()` itself: `solid: true` doesn't
+ * just handle a ray landing inside the prop, it makes *any* containing shape win over anything
+ * farther away - so with the camera sitting inside the holder's own capsule (the ordinary
+ * first-person case), `tryGrab()`'s first, un-skipped cast always self-hit that capsule before ever
+ * reaching the prop, on every single attempt, close range or not. Recovering from that self-hit is
+ * `characterControllerSelfHitSkip()`'s job (see `gg-engine-core-development`'s own notes on it) - so
+ * these tests exercise that recovery through the real `ObjectGrabController` + real
+ * `Rapier3dWorldComponent` + real character-controller collider, not `Rapier3dWorldComponent.raycast()`
+ * in isolation (which, per the above, was never the part that was broken).
+ */
+describe('ObjectGrabController + Rapier3dWorldComponent - end-to-end pick-up range', () => {
+  const setupPedestalAndRadio = (world: Rapier3dWorldComponent, radioPosition: Point3) => {
+    const pedestal = world.factory.createRigidBody(
+      { shape: { shape: 'CYLINDER', radius: 0.5, height: 0.9 }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0, z: 0.45 } },
+    );
+    pedestal.addToWorld({ physicsWorld: world } as any);
+
+    const propBody = world.factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 0.41, y: 0.23, z: 0.49 } }, body: { dynamic: true, mass: 3 } },
+      { position: radioPosition },
+    );
+    propBody.addToWorld({ physicsWorld: world } as any);
+    return new Grabbable3dEntity({ objectBody: propBody });
+  };
+
+  it('grabs a small prop resting on a pedestal even standing very close to it', async () => {
+    const world = new Rapier3dWorldComponent();
+    await world.init();
+    world.gravity = { x: 0, y: 0, z: 0 };
+
+    // Same geometry as the `portal-room` example (and the Ammo regression test referenced above): a
+    // pedestal with a small radio prop resting on top of it.
+    const prop = setupPedestalAndRadio(world, { x: 0, y: 0, z: 1.145 });
+
+    // player capsule radius 0.4 + centersDistance 1.0, matching both the example's own player
+    // options and the Ammo test's holder.
+    const characterController = world.factory.createCharacterController(
+      { radius: 0.4, centersDistance: 1.0 },
+      { position: { x: 0, y: -1.1, z: 1.0 } },
+    );
+    const holder = new CharacterController3dEntity(
+      { radius: 0.4, centersDistance: 1.0, walkSpeed: 4, jumpSpeed: 5, gravity: 9.82 },
+      null,
+      characterController,
+    );
+    holder.onSpawned({ physicsWorld: world } as any);
+    world.simulate(1);
+
+    // playerDistance = 1.1 (same number as the Ammo test) - close enough that the camera (same
+    // height as the prop, a purely horizontal look - no pitch needed to reproduce this) sits well
+    // within the holder capsule's own radius from its central axis, so `tryGrab()`'s first cast is
+    // guaranteed to self-hit that capsule before the retry this test is actually exercising kicks in.
+    const cameraPosition = { x: 0, y: -1.1, z: 1.145 };
+    const camera = { position: cameraPosition, rotation: Qtrn.lookAt(cameraPosition, { x: 0, y: 0, z: 1.145 }) } as any;
+
+    const keyboard = new KeyboardInput();
+    keyboard.start();
+    const mouseInput = new MouseInput();
+    mouseInput.start();
+    const controller = new ObjectGrabController(keyboard, mouseInput, camera, holder);
+    controller.onSpawned({ physicsWorld: world } as any);
+
+    keyboard.emulateKeyDown('KeyE');
+
+    expect(controller.heldObject).toBe(prop);
+  });
+
+  it(
+    'grabs the prop at the exact position/rotation a real gameplay report found it ungrabbable at ' +
+      "(regression: a flat `radius`-sized self-hit skip - characterControllerSelfHitSkip()'s first " +
+      'implementation - cleared the capsule fine for a purely horizontal look, but the real ' +
+      "first-person camera here sits 0.7m above the capsule center (`PlayerCharacterController`'s " +
+      'default eyeHeight) - taller than the capsule half-height (0.5m) - so it starts inside the ' +
+      "rounded top cap, not the cylindrical body; the camera's real downward pitch toward the low " +
+      "radio then meant a flat radius skip landed the retry ray's start point still measurably " +
+      'inside the capsule, self-hitting again and leaving the radio permanently ungrabbable at this ' +
+      'exact spot. Fixed by sphere-tracing the capsule\'s own exact geometry instead of guessing a ' +
+      "flat distance - see `characterControllerSelfHitSkip()`'s own doc)",
+    async () => {
+      const world = new Rapier3dWorldComponent();
+      await world.init();
+      world.gravity = { x: 0, y: 0, z: -9.82 };
+
+      // Exact positions read from the in-game dev console's entity inspector during the failing
+      // report, not guessed.
+      const radioPosition = { x: -0.010856885462999344, y: 0.004407098516821861, z: 0.8990808129310608 };
+      const prop = setupPedestalAndRadio(world, radioPosition);
+
+      const playerPosition = { x: 0.03676546365022659, y: -0.9093552231788635, z: 0.9099816679954529 };
+      const playerRotation = { x: 0, y: 0, z: 0.01860076382738503, w: 0.9998269908264321 };
+      const characterController = world.factory.createCharacterController(
+        { radius: 0.4, centersDistance: 1.0 },
+        { position: playerPosition, rotation: playerRotation },
+      );
+      const holder = new CharacterController3dEntity(
+        { radius: 0.4, centersDistance: 1.0, walkSpeed: 4, jumpSpeed: 4, gravity: 9.82 },
+        null,
+        characterController,
+      );
+      holder.onSpawned({ physicsWorld: world } as any);
+      world.simulate(1);
+
+      // First-person camera at `PlayerCharacterController`'s default eyeHeight (0.7) above the
+      // player capsule's own center, looking at the radio - reproducing the actual aim, not just the
+      // position.
+      const cameraPosition = Pnt3.add(playerPosition, Pnt3.scalarMult(Pnt3.Z, 0.7));
+      const camera = { position: cameraPosition, rotation: Qtrn.lookAt(cameraPosition, radioPosition) } as any;
+
+      const keyboard = new KeyboardInput();
+      keyboard.start();
+      const mouseInput = new MouseInput();
+      mouseInput.start();
+      const controller = new ObjectGrabController(keyboard, mouseInput, camera, holder);
+      controller.onSpawned({ physicsWorld: world } as any);
+
+      keyboard.emulateKeyDown('KeyE');
+
+      expect(controller.heldObject).toBe(prop);
+    },
+  );
+});

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

@@ -5,7 +5,16 @@ import { Rapier3dWorldComponent } from '../../src';
 // maps to world -Z at identity, in this Z-up engine), a degenerate/arbitrary case for
 // `PlayerCharacterController.reset()`'s yaw derivation; every real app sets an actual look
 // direction, so this is the representative case.
-const fakeCamera = () => ({ position: { x: 0, y: 0, z: 0 }, rotation: Qtrn.lookAt(Pnt3.O, Pnt3.Y) }) as any;
+const fakeCamera = () =>
+  ({
+    position: { x: 0, y: 0, z: 0 },
+    rotation: Qtrn.lookAt(Pnt3.O, Pnt3.Y),
+    // `PlayerCharacterController`'s view-mode toggle calls these on its own camera - stubbed here
+    // purely so constructing it doesn't throw; this suite doesn't assert on render-layer state.
+    enableRenderLayer: () => {},
+    disableRenderLayer: () => {},
+    isRenderLayerEnabled: () => true,
+  }) as any;
 
 const setup = async () => {
   const world = new Rapier3dWorldComponent();

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

@@ -0,0 +1,185 @@
+import { Pnt3 } from '@gg-web-engine/core';
+import { Rapier3dFactory, Rapier3dWorldComponent } from '../../src';
+import { Rapier3dRigidBodyComponent } from '../../src/components/rapier-3d-rigid-body.component';
+
+describe('Rapier3dRigidBodyComponent collision events', () => {
+  let world: Rapier3dWorldComponent;
+  let factory: Rapier3dFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new Rapier3dWorldComponent();
+    factory = new Rapier3dFactory(world);
+    await world.init();
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  // Small steps, mirroring Rapier3dTriggerComponent's own spec: a single huge `simulate()` call
+  // detects a contact a whole step late (narrow-phase runs against start-of-step positions), which
+  // would make a "did it fire at all" assertion flaky. `world.simulate()` now dispatches collision
+  // events internally (see `Rapier3dWorldComponent.dispatchCollisionEvents`), so no extra per-step
+  // hook is needed here the way `Rapier3dTriggerComponent.checkOverlaps()` needs calling for triggers.
+  const advance = (totalMs: number, stepMs = 16) => {
+    for (let elapsed = 0; elapsed < totalMs; elapsed += stepMs) {
+      world.simulate(stepMs);
+    }
+  };
+
+  const createFloor = () => {
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 20, y: 20, z: 1 } }, body: { dynamic: false } },
+      { position: { x: 0, y: 0, z: -0.5 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+    return floor;
+  };
+
+  const createBall = (z: number) => {
+    // restitution 0 so the ball settles without bouncing, keeping the "no further onCollisionStart
+    // once resting" assertion below unambiguous.
+    const ball = factory.createRigidBody(
+      { shape: { shape: 'SPHERE', radius: 1 }, body: { dynamic: true, mass: 1, restitution: 0 } },
+      { position: { x: 0, y: 0, z } },
+    );
+    ball.addToWorld({ physicsWorld: world } as any);
+    return ball;
+  };
+
+  it('fires onCollisionStart on the falling body with a resolved otherBody, positive impulse, and a physically sane contact', () => {
+    const floor = createFloor();
+    const ball = createBall(5);
+
+    const ballEvents: any[] = [];
+    ball.onCollisionStart.subscribe(e => ballEvents.push(e));
+
+    advance(2000);
+
+    expect(ballEvents.length).toBeGreaterThanOrEqual(1);
+    const event = ballEvents[0];
+    expect(event.otherBody).toBe(floor);
+    expect(event.impulse).toBeGreaterThan(0);
+    // The ball starts above the floor - `normal` points away from the ball (this body) towards the
+    // floor (`otherBody`), so it should point roughly straight down.
+    expect(event.normal.z).toBeLessThan(-0.9);
+    expect(Math.abs(event.normal.x)).toBeLessThan(0.2);
+    expect(Math.abs(event.normal.y)).toBeLessThan(0.2);
+    // contact point should sit right around the floor's top surface (z = 0), not somewhere wild.
+    expect(event.position.z).toBeGreaterThan(-1);
+    expect(event.position.z).toBeLessThan(1);
+  });
+
+  it('fires the reciprocal onCollisionStart on the other body too, with a consistently-oriented normal/relativeVelocity', () => {
+    const floor = createFloor();
+    const ball = createBall(5);
+
+    const ballEvents: any[] = [];
+    const floorEvents: any[] = [];
+    ball.onCollisionStart.subscribe(e => ballEvents.push(e));
+    floor.onCollisionStart.subscribe(e => floorEvents.push(e));
+
+    advance(2000);
+
+    expect(ballEvents.length).toBeGreaterThanOrEqual(1);
+    expect(floorEvents.length).toBeGreaterThanOrEqual(1);
+    const ballEvent = ballEvents[0];
+    const floorEvent = floorEvents[0];
+
+    expect(floorEvent.otherBody).toBe(ball);
+    expect(ballEvent.otherBody).toBe(floor);
+
+    // floor's normal points away from the floor towards the ball above it (up); the ball's points
+    // away from the ball towards the floor below it (down) - opposite directions.
+    expect(floorEvent.normal.z).toBeGreaterThan(0.9);
+    expect(ballEvent.normal.z).toBeLessThan(-0.9);
+
+    // relativeVelocity is "otherBody's velocity relative to this body", read from each body's own
+    // `linvel()` *after* this step's solve already ran (see `Rapier3dWorldComponent.
+    // dispatchCollisionEvents`'s doc) - not the pre-response approach velocity the ball actually hit
+    // at, since Rapier's constraint solver has already resolved the contact (and, with the default
+    // Baumgarte-style bias, can leave a small outward/separating residual velocity behind) by the
+    // time `drainCollisionEvents` reports it as `started`. What must still hold regardless: the two
+    // reciprocal readings are exact negations of each other (floor is stationary throughout, so this
+    // is really just `-ball.linvel().z` vs `ball.linvel().z`).
+    expect(floorEvent.relativeVelocity.z).toBeCloseTo(-ballEvent.relativeVelocity.z, 5);
+
+    expect(floorEvent.impulse).toBeCloseTo(ballEvent.impulse, 5);
+  });
+
+  it('does not keep re-firing onCollisionStart for a body resting stably on another', () => {
+    const floor = createFloor();
+    const ball = createBall(3);
+    void floor;
+
+    let startCount = 0;
+    ball.onCollisionStart.subscribe(() => startCount++);
+
+    advance(1500); // fall and land
+    const countAfterLanding = startCount;
+    expect(countAfterLanding).toBeGreaterThanOrEqual(1);
+
+    advance(1500); // keep resting, several hundred more simulate() calls
+    expect(startCount).toBe(countAfterLanding);
+  });
+
+  it('fires onCollisionEnd when a body is knocked away and separates from what it was touching', () => {
+    const floor = createFloor();
+    const ball = createBall(3);
+
+    let endedWith: Rapier3dRigidBodyComponent | null | undefined;
+    let endCount = 0;
+    ball.onCollisionEnd.subscribe(other => {
+      endCount++;
+      endedWith = other;
+    });
+
+    advance(1500); // let it land and settle
+    expect(endCount).toBe(0);
+
+    // zero gravity so the teleported ball doesn't immediately fall back down and re-collide within
+    // this test's own observation window
+    world.gravity = Pnt3.O;
+    ball.position = { x: 0, y: 0, z: 20 };
+    advance(500);
+
+    expect(endCount).toBeGreaterThanOrEqual(1);
+    expect(endedWith).toBe(floor);
+  });
+
+  it("does not fire a rigid body's onCollisionStart for a trigger overlap (triggers stay sensor-only)", () => {
+    world.gravity = Pnt3.O;
+    const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
+    trigger.addToWorld({ physicsWorld: world } as any);
+
+    const ball = createBall(0); // spawned already overlapping the trigger volume
+
+    let ballCollisionStarts = 0;
+    ball.onCollisionStart.subscribe(() => ballCollisionStarts++);
+    let triggerEnters = 0;
+    trigger.onEntityEntered.subscribe(() => triggerEnters++);
+
+    advance(500);
+    trigger.checkOverlaps();
+
+    expect(triggerEnters).toBeGreaterThanOrEqual(1);
+    expect(ballCollisionStarts).toBe(0);
+  });
+
+  it('completes onCollisionStart/onCollisionEnd on dispose, matching matter/ammo', () => {
+    const ball = createBall(0);
+
+    let startCompleted = false;
+    let endCompleted = false;
+    ball.onCollisionStart.subscribe({ complete: () => (startCompleted = true) });
+    ball.onCollisionEnd.subscribe({ complete: () => (endCompleted = true) });
+
+    ball.dispose();
+
+    expect(startCompleted).toBe(true);
+    expect(endCompleted).toBe(true);
+  });
+});

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

@@ -2,7 +2,6 @@ import { Pnt3 } from '@gg-web-engine/core';
 import { Rapier3dFactory, Rapier3dWorldComponent } from '../../src';
 
 describe(`Rapier3dTriggerComponent`, () => {
-
   let world: Rapier3dWorldComponent;
   let factory: Rapier3dFactory;
   beforeEach(async () => {
@@ -39,20 +38,23 @@ describe(`Rapier3dTriggerComponent`, () => {
   it(`should detect object intersection`, async () => {
     const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
     trigger.addToWorld({ physicsWorld: world } as any);
-    const ball = factory.createRigidBody({
-      shape: { shape: 'SPHERE', radius: 1 },
-      body: { dynamic: true, mass: 1 },
-    }, { position: { x: 0, y: 0, z: 12 } });
+    const ball = factory.createRigidBody(
+      {
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { dynamic: true, mass: 1 },
+      },
+      { position: { x: 0, y: 0, z: 12 } },
+    );
     ball.addToWorld({ physicsWorld: world } as any);
     ball.linearVelocity = { x: 0, y: 0, z: -10 };
     let enterRegistered = false;
     let exitRegistered = false;
-    trigger.onEntityEntered.subscribe(((obj) => {
+    trigger.onEntityEntered.subscribe(obj => {
       enterRegistered = obj === ball;
-    }));
-    trigger.onEntityLeft.subscribe(((obj) => {
+    });
+    trigger.onEntityLeft.subscribe(obj => {
       exitRegistered = obj === ball;
-    }));
+    });
     advance(500, () => trigger.checkOverlaps()); // trigger entity performs that on tick
     expect(enterRegistered).toBe(false);
     expect(exitRegistered).toBe(false);
@@ -65,16 +67,19 @@ describe(`Rapier3dTriggerComponent`, () => {
   it(`should detect end of object intersection`, async () => {
     const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
     trigger.addToWorld({ physicsWorld: world } as any);
-    const ball = factory.createRigidBody({
-      shape: { shape: 'SPHERE', radius: 1 },
-      body: { dynamic: true, mass: 1 },
-    }, { position: { x: 0, y: 0, z: 12 } });
+    const ball = factory.createRigidBody(
+      {
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { dynamic: true, mass: 1 },
+      },
+      { position: { x: 0, y: 0, z: 12 } },
+    );
     ball.addToWorld({ physicsWorld: world } as any);
     ball.linearVelocity = { x: 0, y: 0, z: -10 };
     let exitRegistered = false;
-    trigger.onEntityLeft.subscribe(((obj) => {
+    trigger.onEntityLeft.subscribe(obj => {
       exitRegistered = obj === ball;
-    }));
+    });
     advance(1000, () => trigger.checkOverlaps());
     expect(exitRegistered).toBe(false);
     advance(1000, () => trigger.checkOverlaps());
@@ -84,15 +89,18 @@ describe(`Rapier3dTriggerComponent`, () => {
   it(`should fire object intersection if spawned inside`, async () => {
     const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
     trigger.addToWorld({ physicsWorld: world } as any);
-    const ball = factory.createRigidBody({
-      shape: { shape: 'SPHERE', radius: 1 },
-      body: { dynamic: true, mass: 1 },
-    }, { position: { x: 0, y: 0, z: 0 } });
+    const ball = factory.createRigidBody(
+      {
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { dynamic: true, mass: 1 },
+      },
+      { position: { x: 0, y: 0, z: 0 } },
+    );
     ball.addToWorld({ physicsWorld: world } as any);
     let enterRegistered = false;
-    trigger.onEntityEntered.subscribe(((obj) => {
+    trigger.onEntityEntered.subscribe(obj => {
       enterRegistered = obj === ball;
-    }));
+    });
     world.simulate(1000);
     trigger.checkOverlaps();
     expect(enterRegistered).toBe(true);
@@ -101,15 +109,18 @@ describe(`Rapier3dTriggerComponent`, () => {
   it(`should fire end of object intersection if trigger removed`, async () => {
     const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
     trigger.addToWorld({ physicsWorld: world } as any);
-    const ball = factory.createRigidBody({
-      shape: { shape: 'SPHERE', radius: 1 },
-      body: { dynamic: true, mass: 1 },
-    }, { position: { x: 0, y: 0, z: 0 } });
+    const ball = factory.createRigidBody(
+      {
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { dynamic: true, mass: 1 },
+      },
+      { position: { x: 0, y: 0, z: 0 } },
+    );
     ball.addToWorld({ physicsWorld: world } as any);
     let exitRegistered = false;
-    trigger.onEntityLeft.subscribe(((obj) => {
+    trigger.onEntityLeft.subscribe(obj => {
       exitRegistered = obj === ball;
-    }));
+    });
     world.simulate(1);
     trigger.checkOverlaps();
     trigger.removeFromWorld({ physicsWorld: world } as any);
@@ -119,15 +130,18 @@ describe(`Rapier3dTriggerComponent`, () => {
   it(`should fire end of object intersection if object removed`, async () => {
     const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
     trigger.addToWorld({ physicsWorld: world } as any);
-    const ball = factory.createRigidBody({
-      shape: { shape: 'SPHERE', radius: 1 },
-      body: { dynamic: true, mass: 1 },
-    }, { position: { x: 0, y: 0, z: 0 } });
+    const ball = factory.createRigidBody(
+      {
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { dynamic: true, mass: 1 },
+      },
+      { position: { x: 0, y: 0, z: 0 } },
+    );
     ball.addToWorld({ physicsWorld: world } as any);
     let exitRegistered = false;
-    trigger.onEntityLeft.subscribe(((obj) => {
+    trigger.onEntityLeft.subscribe(obj => {
       exitRegistered = obj === ball;
-    }));
+    });
     world.simulate(1);
     trigger.checkOverlaps();
     ball.removeFromWorld({ physicsWorld: world } as any);
@@ -135,4 +149,25 @@ describe(`Rapier3dTriggerComponent`, () => {
     trigger.checkOverlaps();
     expect(exitRegistered).toBe(true);
   });
+
+  it('completes onEntityEntered/onEntityLeft (and the inherited collision subjects) on dispose', () => {
+    const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 10, y: 10, z: 10 } });
+    trigger.addToWorld({ physicsWorld: world } as any);
+
+    let enterCompleted = false;
+    let leftCompleted = false;
+    let startCompleted = false;
+    let endCompleted = false;
+    trigger.onEntityEntered.subscribe({ complete: () => (enterCompleted = true) });
+    trigger.onEntityLeft.subscribe({ complete: () => (leftCompleted = true) });
+    trigger.onCollisionStart.subscribe({ complete: () => (startCompleted = true) });
+    trigger.onCollisionEnd.subscribe({ complete: () => (endCompleted = true) });
+
+    trigger.dispose();
+
+    expect(enterCompleted).toBe(true);
+    expect(leftCompleted).toBe(true);
+    expect(startCompleted).toBe(true);
+    expect(endCompleted).toBe(true);
+  });
 });

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

@@ -87,6 +87,34 @@ describe('Rapier3dWorldComponent', () => {
     });
   });
 
+  describe('Sleeping bodies', () => {
+    it(
+      'wakes a sleeping body when position/rotation/velocity is set programmatically ' +
+        '(regression: Rapier skips a sleeping body\'s island entirely during step(), so a ' +
+        'transform/velocity write passing wakeUp=false was silently never simulated)',
+      () => {
+        const ball = world.factory.createRigidBody(
+          { shape: { shape: 'SPHERE', radius: 1 }, body: { dynamic: true, mass: 5 } },
+          { position: { x: 0, y: 0, z: 0 } },
+        );
+        ball.addToWorld({ physicsWorld: world } as any);
+
+        // let it fall asleep: zero gravity (see beforeEach) and zero velocity means nothing ever
+        // disturbs it, so Rapier's own sleep threshold/timer runs out on its own.
+        for (let i = 0; i < 200; i++) {
+          world.simulate(60);
+        }
+        expect((ball as any).nativeBody.isSleeping()).toBe(true);
+
+        ball.linearVelocity = { x: 1, y: 0, z: 0 };
+        for (let i = 0; i < 60; i++) {
+          world.simulate(60);
+        }
+        expect(ball.position.x).toBeGreaterThan(0.5);
+      },
+    );
+  });
+
   describe('Raycast', () => {
 
     it('should return no hit when ray does not intersect any object', () => {