@gg-web-engine/matter 0.0.66 → 0.0.68

package/dist/components/matter-rigid-body.component.d.ts

@@ -1,5 +1,6 @@
-import { CollisionGroup, DebugBody2DSettings, Entity2d, IRigidBody2dComponent, Point2, Shape2DDescriptor } from '@gg-web-engine/core';
+import { CollisionEvent, CollisionGroup, DebugBody2DSettings, Entity2d, IRigidBody2dComponent, Point2, Shape2DDescriptor } from '@gg-web-engine/core';
 import { Body } from 'matter-js';
+import { Observable, Subject } from 'rxjs';
 import { MatterGgWorld, MatterPhysicsTypeDocRepo } from '../types';
 export declare class MatterRigidBodyComponent implements IRigidBody2dComponent<MatterPhysicsTypeDocRepo> {
     nativeBody: Body;
@@ -17,7 +18,23 @@ export declare class MatterRigidBodyComponent implements IRigidBody2dComponent<M
     readonly debugBodySettings: DebugBody2DSettings;
     protected _interactWithCGsMask: number;
     protected _ownCGsMask: number;
+    get onCollisionStart(): Observable<CollisionEvent<Point2, MatterRigidBodyComponent>>;
+    get onCollisionEnd(): Observable<MatterRigidBodyComponent | null>;
+    protected readonly onCollisionStart$: Subject<CollisionEvent<Point2, MatterRigidBodyComponent>>;
+    protected readonly onCollisionEnd$: Subject<MatterRigidBodyComponent | null>;
+    /** Other rigid bodies this body is currently touching (non-sensor contact only), tracked so
+     * `removeFromWorld` can tell them apart to emit `onCollisionEnd(null)` per that member's
+     * documented "other body removed while still in contact" case. Maintained exclusively via
+     * `notifyCollisionStart`/`notifyCollisionEnd`, called by `MatterWorldComponent`'s single
+     * world-wide `collisionStart`/`collisionEnd` listener - not touched directly by anything else. */
+    protected readonly currentContacts: Set<MatterRigidBodyComponent>;
     constructor(nativeBody: Body, shape: Shape2DDescriptor);
+    /** @internal called by `MatterWorldComponent`'s global `collisionStart` listener - not part of
+     * this component's public API surface. */
+    notifyCollisionStart(collisionEvent: CollisionEvent<Point2, MatterRigidBodyComponent>): void;
+    /** @internal called by `MatterWorldComponent`'s global `collisionEnd` listener - not part of
+     * this component's public API surface. */
+    notifyCollisionEnd(otherBody: MatterRigidBodyComponent | null): void;
     get interactWithCollisionGroups(): ReadonlyArray<CollisionGroup>;
     set interactWithCollisionGroups(value: ReadonlyArray<CollisionGroup> | 'all');
     get ownCollisionGroups(): ReadonlyArray<CollisionGroup>;

package/dist/components/matter-rigid-body.component.js

@@ -1,5 +1,6 @@
 import { BitMask, DebugBody2DSettings, Pnt2, } from '@gg-web-engine/core';
 import { Body, Composite, Vector } from 'matter-js';
+import { Subject } from 'rxjs';
 // FIXME why this needs to be introduced? investigate units in matter.js
 const MATTER_VELOCITY_SCALE = 0.0166667;
 export class MatterRigidBodyComponent {
@@ -27,6 +28,12 @@ export class MatterRigidBodyComponent {
     set angularVelocity(value) {
         Body.setAngularVelocity(this.nativeBody, value);
     }
+    get onCollisionStart() {
+        return this.onCollisionStart$.asObservable();
+    }
+    get onCollisionEnd() {
+        return this.onCollisionEnd$.asObservable();
+    }
     constructor(nativeBody, shape) {
         this.nativeBody = nativeBody;
         this.shape = shape;
@@ -37,8 +44,30 @@ export class MatterRigidBodyComponent {
             : { type: 'RIGID_STATIC' }, this.shape);
         this._interactWithCGsMask = BitMask.full(16);
         this._ownCGsMask = BitMask.full(16);
+        this.onCollisionStart$ = new Subject();
+        this.onCollisionEnd$ = new Subject();
+        /** Other rigid bodies this body is currently touching (non-sensor contact only), tracked so
+         * `removeFromWorld` can tell them apart to emit `onCollisionEnd(null)` per that member's
+         * documented "other body removed while still in contact" case. Maintained exclusively via
+         * `notifyCollisionStart`/`notifyCollisionEnd`, called by `MatterWorldComponent`'s single
+         * world-wide `collisionStart`/`collisionEnd` listener - not touched directly by anything else. */
+        this.currentContacts = new Set();
         this.updateCollisionFilter();
     }
+    /** @internal called by `MatterWorldComponent`'s global `collisionStart` listener - not part of
+     * this component's public API surface. */
+    notifyCollisionStart(collisionEvent) {
+        this.currentContacts.add(collisionEvent.otherBody);
+        this.onCollisionStart$.next(collisionEvent);
+    }
+    /** @internal called by `MatterWorldComponent`'s global `collisionEnd` listener - not part of
+     * this component's public API surface. */
+    notifyCollisionEnd(otherBody) {
+        if (otherBody) {
+            this.currentContacts.delete(otherBody);
+        }
+        this.onCollisionEnd$.next(otherBody);
+    }
     get interactWithCollisionGroups() {
         return BitMask.unpack(this._interactWithCGsMask, 16);
     }
@@ -88,15 +117,27 @@ export class MatterRigidBodyComponent {
     removeFromWorld(world, dispose = false) {
         Composite.remove(world.physicsWorld.matterWorld, this.nativeBody);
         world.physicsWorld.removed$.next(this);
+        // this body is leaving the world while still touching others - per `onCollisionEnd`'s own
+        // contract, each of those bodies sees `null` (no further contact geometry is available), not a
+        // dangling reference to a body no longer in the world.
+        for (const other of this.currentContacts) {
+            other.notifyCollisionEnd(null);
+            other.currentContacts.delete(this);
+        }
+        this.currentContacts.clear();
         if (dispose) {
             this.dispose();
         }
     }
     // matter.js bodies are plain JS objects with no native/WASM handle - ordinary GC reclaims them
-    // once `Composite.remove` above drops the engine's own reference, so there's nothing to free here
-    // at this level. `MatterTriggerComponent` overrides this to complete its own RxJS subjects, which
-    // *do* need an explicit dispose.
-    dispose() { }
+    // once `Composite.remove` above drops the engine's own reference, so there's nothing to free
+    // beyond completing this component's own RxJS subjects. `MatterTriggerComponent` overrides this
+    // to also complete its own `onEnter$`/`onLeft$` subjects, calling back into this via `super.
+    // dispose()`.
+    dispose() {
+        this.onCollisionStart$.complete();
+        this.onCollisionEnd$.complete();
+    }
     resetMotion() {
         Body.setVelocity(this.nativeBody, Pnt2.O);
         Body.setAngularVelocity(this.nativeBody, 0);

package/dist/components/matter-trigger.component.d.ts

@@ -14,13 +14,14 @@ export declare class MatterTriggerComponent extends MatterRigidBodyComponent imp
     readonly debugBodySettings: DebugBody2DSettings;
     protected intersectionsAmount: number;
     protected currentOverlaps: Set<MatterRigidBodyComponent>;
-    private onCollisionStart;
-    private onCollisionEnd;
+    private handleCollisionStart;
+    private handleCollisionEnd;
     constructor(nativeBody: Body, shape: Shape2DDescriptor, world: MatterWorldComponent);
     addToWorld(world: MatterGgWorld): void;
     removeFromWorld(world: MatterGgWorld, dispose?: boolean): void;
-    /** Completes `onEnter$`/`onLeft$` - `MatterRigidBodyComponent.dispose()` is a no-op (see its own
-     * doc), so this is the only place these two subjects ever get completed. */
+    /** Completes `onEnter$`/`onLeft$` on top of `MatterRigidBodyComponent.dispose()`'s own
+     * `onCollisionStart$`/`onCollisionEnd$` completion (via `super.dispose()`) - this trigger's own
+     * enter/exit subjects are a separate pair this subclass owns and must complete itself. */
     dispose(): void;
     checkOverlaps(): void;
     clone(): MatterTriggerComponent;

package/dist/components/matter-trigger.component.js

@@ -9,7 +9,7 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
     get onEntityLeft() {
         return this.onLeft$.asObservable();
     }
-    onCollisionStart(event) {
+    handleCollisionStart(event) {
         for (const pair of event.pairs) {
             let body = null;
             if (pair.bodyA === this.nativeBody) {
@@ -26,7 +26,7 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
             }
         }
     }
-    onCollisionEnd(event) {
+    handleCollisionEnd(event) {
         for (const pair of event.pairs) {
             let body = null;
             if (pair.bodyA === this.nativeBody) {
@@ -61,8 +61,8 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
                 this.intersectionsAmount--;
             }
         });
-        this.onCollisionStart = this.onCollisionStart.bind(this);
-        this.onCollisionEnd = this.onCollisionEnd.bind(this);
+        this.handleCollisionStart = this.handleCollisionStart.bind(this);
+        this.handleCollisionEnd = this.handleCollisionEnd.bind(this);
     }
     addToWorld(world) {
         if (world.physicsWorld != this.world) {
@@ -71,20 +71,21 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         this.intersectionsAmount = 0;
         this.currentOverlaps.clear();
         super.addToWorld(world);
-        Events.on(world.physicsWorld.matterEngine, 'collisionStart', this.onCollisionStart);
-        Events.on(world.physicsWorld.matterEngine, 'collisionEnd', this.onCollisionEnd);
+        Events.on(world.physicsWorld.matterEngine, 'collisionStart', this.handleCollisionStart);
+        Events.on(world.physicsWorld.matterEngine, 'collisionEnd', this.handleCollisionEnd);
     }
     removeFromWorld(world, dispose) {
-        Events.off(world.physicsWorld.matterEngine, 'collisionStart', this.onCollisionStart);
-        Events.off(world.physicsWorld.matterEngine, 'collisionEnd', this.onCollisionEnd);
+        Events.off(world.physicsWorld.matterEngine, 'collisionStart', this.handleCollisionStart);
+        Events.off(world.physicsWorld.matterEngine, 'collisionEnd', this.handleCollisionEnd);
         for (const body of this.currentOverlaps) {
             this.onLeft$.next(body);
         }
         this.currentOverlaps.clear();
         super.removeFromWorld(world, dispose);
     }
-    /** Completes `onEnter$`/`onLeft$` - `MatterRigidBodyComponent.dispose()` is a no-op (see its own
-     * doc), so this is the only place these two subjects ever get completed. */
+    /** Completes `onEnter$`/`onLeft$` on top of `MatterRigidBodyComponent.dispose()`'s own
+     * `onCollisionStart$`/`onCollisionEnd$` completion (via `super.dispose()`) - this trigger's own
+     * enter/exit subjects are a separate pair this subclass owns and must complete itself. */
     dispose() {
         this.onEnter$.complete();
         this.onLeft$.complete();

package/dist/components/matter-world.component.d.ts

@@ -13,12 +13,42 @@ export declare class MatterWorldComponent implements IPhysicsWorld2dComponent<Ma
     readonly added$: Subject<MatterRigidBodyComponent | MatterTriggerComponent>;
     readonly removed$: Subject<MatterRigidBodyComponent | MatterTriggerComponent>;
     readonly children: (MatterRigidBodyComponent | MatterTriggerComponent)[];
+    /** Mirrors the rapier packages' `handleIdEntityMap` pattern: `Body.id` (matter-js's own
+     * globally-unique numeric id, assigned once per body via `Body.nextId` and stable for its whole
+     * lifetime) to component, kept in sync alongside `children` so `findRigidBody` - called once per
+     * collision pair, per step - is an O(1) lookup instead of an O(n) `Array.find` scan. */
+    readonly handleIdEntityMap: Map<number, MatterRigidBodyComponent>;
     private _gravity;
     get gravity(): Point2;
     set gravity(value: Point2);
     readonly mainCollisionGroup: CollisionGroup;
     constructor();
     init(): Promise<void>;
+    private findRigidBody;
+    /**
+     * Wires `IRigidBody2dComponent.onCollisionStart` for every non-sensor pair in the world, off
+     * matter-js's own `Matter.Events` 'collisionStart' (fired once per engine, not per-body - see
+     * `gg-engine-physics-adapter-matter` for why it's registered here rather than per component).
+     * `pair.isSensor` (true whenever either side is a trigger's underlying body, which always has
+     * `isSensor: true` - see `MatterTriggerComponent`'s constructor) is skipped entirely, so a
+     * trigger overlapping a rigid body only ever fires the trigger's own `onEntityEntered`, never
+     * this.
+     *
+     * Impulse: at the point this event fires, matter-js hasn't run `Resolver.solveVelocity` yet for
+     * this step (that happens later in `Engine.update`, whose event order is
+     * collisionStart → position solve → velocity solve → collisionActive → collisionEnd) - so a
+     * freshly-created pair's `pair.contacts[*].normalImpulse`/`tangentImpulse` are still their
+     * just-initialized `0`, not yet a meaningful number, for every pair this event could ever
+     * report. Rather than reading always-zero data, `impulse` here is estimated as
+     * `|relativeVelocity| * min(massA, massB)` (a rough "how hard did they hit" proxy - a static
+     * body's `mass` is `Infinity`, so `min` naturally reduces to the dynamic side's mass when one
+     * side is static).
+     */
+    private handleCollisionStart;
+    /** Wires `IRigidBody2dComponent.onCollisionEnd` for every non-sensor pair that just stopped
+     * touching - see `handleCollisionStart`'s doc for why sensor pairs are skipped and why this is
+     * registered once per engine rather than per-body. */
+    private handleCollisionEnd;
     protected lockedCollisionGroups: number[];
     registerCollisionGroup(): CollisionGroup;
     deregisterCollisionGroup(group: CollisionGroup): void;

package/dist/components/matter-world.component.js

@@ -7,9 +7,33 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Engine } from 'matter-js';
+import { Pnt2, } from '@gg-web-engine/core';
+import { Engine, Events } from 'matter-js';
 import { MatterFactory } from '../matter-factory';
 import { Subject } from 'rxjs';
+/**
+ * Averages matter-js's collision support points into a single representative contact point for
+ * `CollisionEvent.position`. `collision.supports` is *always* a fixed-length-2 array
+ * (`[null, null]` initially - see `Collision.js`'s `Collision.create`), but `@types/matter-js`
+ * 0.20.2 types it as plain `Vector[]` with no way to tell which slots are actually populated -
+ * only the first `collision.supportCount` entries are ever real, the rest can be `null` (or stale
+ * leftovers from a previous collision reusing the same record). Reading past `supportCount` (or
+ * trusting `.length`, always 2) crashes on the `null` slot - always slice to `supportCount` first.
+ */
+function averageSupports(collision) {
+    // `supportCount` is real at runtime (see `Collision.js`) but missing from `@types/matter-js`
+    // 0.20.2's `Collision` typing entirely - cast narrowly just for this one field.
+    const supportCount = collision.supportCount;
+    const supports = collision.supports.slice(0, supportCount);
+    if (supports.length === 0) {
+        return Pnt2.O;
+    }
+    let sum = Pnt2.O;
+    for (const support of supports) {
+        sum = Pnt2.add(sum, support);
+    }
+    return Pnt2.scalarMult(sum, 1 / supports.length);
+}
 // TODO probably should be configurable in world
 const MATTER_WORLD_SCALE = 0.0001;
 export class MatterWorldComponent {
@@ -34,21 +58,105 @@ export class MatterWorldComponent {
         this.added$ = new Subject();
         this.removed$ = new Subject();
         this.children = [];
+        /** Mirrors the rapier packages' `handleIdEntityMap` pattern: `Body.id` (matter-js's own
+         * globally-unique numeric id, assigned once per body via `Body.nextId` and stable for its whole
+         * lifetime) to component, kept in sync alongside `children` so `findRigidBody` - called once per
+         * collision pair, per step - is an O(1) lookup instead of an O(n) `Array.find` scan. */
+        this.handleIdEntityMap = new Map();
         this._gravity = { x: 0, y: 9.82 };
         this.mainCollisionGroup = 0;
         this.lockedCollisionGroups = [];
         this.lastDelta = 0;
-        this.added$.subscribe(c => this.children.push(c));
-        this.removed$.subscribe(c => this.children.splice(this.children.indexOf(c), 1));
+        this.added$.subscribe(c => {
+            this.children.push(c);
+            this.handleIdEntityMap.set(c.nativeBody.id, c);
+        });
+        this.removed$.subscribe(c => {
+            this.children.splice(this.children.indexOf(c), 1);
+            this.handleIdEntityMap.delete(c.nativeBody.id);
+        });
         this.factory = new MatterFactory(this);
+        this.handleCollisionStart = this.handleCollisionStart.bind(this);
+        this.handleCollisionEnd = this.handleCollisionEnd.bind(this);
     }
     init() {
         return __awaiter(this, void 0, void 0, function* () {
             this.matterEngine_ = Engine.create({
                 gravity: Object.assign(Object.assign({}, this._gravity), { scale: MATTER_WORLD_SCALE }),
             });
+            Events.on(this.matterEngine_, 'collisionStart', this.handleCollisionStart);
+            Events.on(this.matterEngine_, 'collisionEnd', this.handleCollisionEnd);
         });
     }
+    findRigidBody(nativeBody) {
+        return this.handleIdEntityMap.get(nativeBody.id);
+    }
+    /**
+     * Wires `IRigidBody2dComponent.onCollisionStart` for every non-sensor pair in the world, off
+     * matter-js's own `Matter.Events` 'collisionStart' (fired once per engine, not per-body - see
+     * `gg-engine-physics-adapter-matter` for why it's registered here rather than per component).
+     * `pair.isSensor` (true whenever either side is a trigger's underlying body, which always has
+     * `isSensor: true` - see `MatterTriggerComponent`'s constructor) is skipped entirely, so a
+     * trigger overlapping a rigid body only ever fires the trigger's own `onEntityEntered`, never
+     * this.
+     *
+     * Impulse: at the point this event fires, matter-js hasn't run `Resolver.solveVelocity` yet for
+     * this step (that happens later in `Engine.update`, whose event order is
+     * collisionStart → position solve → velocity solve → collisionActive → collisionEnd) - so a
+     * freshly-created pair's `pair.contacts[*].normalImpulse`/`tangentImpulse` are still their
+     * just-initialized `0`, not yet a meaningful number, for every pair this event could ever
+     * report. Rather than reading always-zero data, `impulse` here is estimated as
+     * `|relativeVelocity| * min(massA, massB)` (a rough "how hard did they hit" proxy - a static
+     * body's `mass` is `Infinity`, so `min` naturally reduces to the dynamic side's mass when one
+     * side is static).
+     */
+    handleCollisionStart(event) {
+        for (const pair of event.pairs) {
+            if (pair.isSensor) {
+                continue;
+            }
+            const compA = this.findRigidBody(pair.bodyA);
+            const compB = this.findRigidBody(pair.bodyB);
+            if (!compA || !compB) {
+                continue;
+            }
+            const position = averageSupports(pair.collision);
+            // `pair.collision.normal` is normalized, but - despite `Collision.js`'s own inline comment
+            // claiming it's "facing away from bodyA" - empirically (verified against a floor/falling-ball
+            // scenario with known relative positions) it always ends up facing the *opposite* way: away
+            // from `pair.bodyB`, towards `pair.bodyA`. `Collision.js`'s flip check
+            // (`if (normalX * deltaX + normalY * deltaY >= 0) { negate }`, where `delta = bodyB.position -
+            // bodyA.position`) guarantees the *final* normal always has a non-positive dot product with
+            // the A→B delta - i.e. it points away from B, not away from A as the comment says. So it's
+            // `compB`'s event that gets the raw value here, and `compA`'s that needs the negation - the
+            // opposite pairing a literal reading of the upstream comment would suggest.
+            const normalFromB = Pnt2.clone(pair.collision.normal);
+            const normalFromA = Pnt2.neg(normalFromB);
+            const relativeVelocityForA = Pnt2.sub(compB.linearVelocity, compA.linearVelocity);
+            const relativeVelocityForB = Pnt2.neg(relativeVelocityForA);
+            const impulse = Pnt2.len(relativeVelocityForA) * Math.min(compA.nativeBody.mass, compB.nativeBody.mass);
+            const baseEvent = { position, impulse };
+            compA.notifyCollisionStart(Object.assign(Object.assign({}, baseEvent), { otherBody: compB, normal: normalFromA, relativeVelocity: relativeVelocityForA }));
+            compB.notifyCollisionStart(Object.assign(Object.assign({}, baseEvent), { otherBody: compA, normal: normalFromB, relativeVelocity: relativeVelocityForB }));
+        }
+    }
+    /** Wires `IRigidBody2dComponent.onCollisionEnd` for every non-sensor pair that just stopped
+     * touching - see `handleCollisionStart`'s doc for why sensor pairs are skipped and why this is
+     * registered once per engine rather than per-body. */
+    handleCollisionEnd(event) {
+        for (const pair of event.pairs) {
+            if (pair.isSensor) {
+                continue;
+            }
+            const compA = this.findRigidBody(pair.bodyA);
+            const compB = this.findRigidBody(pair.bodyB);
+            if (!compA || !compB) {
+                continue;
+            }
+            compA.notifyCollisionEnd(compB);
+            compB.notifyCollisionEnd(compA);
+        }
+    }
     registerCollisionGroup() {
         for (let i = 1; i < 16; i++) {
             if (!this.lockedCollisionGroups.includes(i)) {
@@ -69,6 +177,8 @@ export class MatterWorldComponent {
         throw new Error('Ray casting is not implemented for Matter.js');
     }
     dispose() {
+        Events.off(this.matterEngine, 'collisionStart', this.handleCollisionStart);
+        Events.off(this.matterEngine, 'collisionEnd', this.handleCollisionEnd);
         Engine.clear(this.matterEngine);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gg-web-engine/matter",
-  "version": "0.0.66",
+  "version": "0.0.68",
   "description": "An attempt to create open source game engine for browser",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@types/matter-js": "0.20.2",
-    "@gg-web-engine/core": "0.0.66",
+    "@gg-web-engine/core": "0.0.68",
     "@types/jest": "^30.0.0",
     "@types/node": "^26.4.0",
     "jest": "^30.5.0",
@@ -42,7 +42,7 @@
     "typescript": "~6.0.3"
   },
   "peerDependencies": {
-    "@gg-web-engine/core": "0.0.66",
+    "@gg-web-engine/core": "0.0.68",
     "matter-js": "0.20.0",
     "rxjs": "7.8.2"
   },

package/test/components/matter-rigid-body-collision.spec.ts

@@ -0,0 +1,187 @@
+import { CollisionEvent, Pnt2, Point2 } from '@gg-web-engine/core';
+import { MatterFactory, MatterRigidBodyComponent, MatterWorldComponent } from '../../src';
+
+describe('MatterRigidBodyComponent collision events', () => {
+  let world: MatterWorldComponent;
+  let factory: MatterFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new MatterWorldComponent();
+    factory = new MatterFactory(world);
+    await world.init();
+    world.gravity = Pnt2.O;
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it('should fire onCollisionStart reciprocally, with a sane position/normal, when a falling body lands on a floor', () => {
+    // static floor, top edge sits at y = -5
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+
+    const ball = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
+      { position: { x: 0, y: -20 } },
+    );
+    ball.addToWorld({ physicsWorld: world } as any);
+    ball.linearVelocity = { x: 0, y: 10 };
+    ball.nativeBody.frictionAir = 0;
+
+    const ballEvents: CollisionEvent<Point2, MatterRigidBodyComponent>[] = [];
+    const floorEvents: CollisionEvent<Point2, MatterRigidBodyComponent>[] = [];
+    ball.onCollisionStart.subscribe(e => ballEvents.push(e));
+    floor.onCollisionStart.subscribe(e => floorEvents.push(e));
+
+    for (let i = 0; i < 200 && ballEvents.length === 0; i++) {
+      world.simulate(16);
+    }
+
+    expect(ballEvents.length).toBeGreaterThan(0);
+    expect(floorEvents.length).toBeGreaterThan(0);
+
+    const ballHit = ballEvents[0];
+    expect(ballHit.otherBody).toBe(floor);
+    expect(ballHit.impulse).toBeGreaterThan(0);
+    // ball fell straight down onto a flat floor - normal (pointing away from the ball, towards the
+    // floor) should point roughly downward (+y, matter.js's default gravity/screen convention)
+    expect(ballHit.normal.y).toBeGreaterThan(0.5);
+
+    const floorHit = floorEvents[0];
+    expect(floorHit.otherBody).toBe(ball);
+    // reciprocal event: normal seen by the floor should point the opposite way (towards the ball)
+    expect(floorHit.normal.y).toBeLessThan(-0.5);
+    expect(floorHit.normal.x).toBeCloseTo(-ballHit.normal.x, 5);
+    expect(floorHit.normal.y).toBeCloseTo(-ballHit.normal.y, 5);
+    // relative velocity is opposite too (otherBody velocity relative to self, on each side)
+    expect(floorHit.relativeVelocity.x).toBeCloseTo(-ballHit.relativeVelocity.x, 5);
+    expect(floorHit.relativeVelocity.y).toBeCloseTo(-ballHit.relativeVelocity.y, 5);
+  });
+
+  it('should not keep re-firing onCollisionStart while a body rests stably on another', () => {
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+
+    const ball = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
+      { position: { x: 0, y: -20 } },
+    );
+    ball.addToWorld({ physicsWorld: world } as any);
+    ball.linearVelocity = { x: 0, y: 10 };
+    ball.nativeBody.frictionAir = 0;
+
+    world.gravity = { x: 0, y: 1 };
+
+    let startCount = 0;
+    ball.onCollisionStart.subscribe(() => startCount++);
+
+    // simulate until it lands and settles
+    for (let i = 0; i < 200; i++) {
+      world.simulate(16);
+    }
+    expect(startCount).toBeGreaterThan(0);
+    const countAfterLanding = startCount;
+
+    // continue simulating - resting contact must not re-fire onCollisionStart
+    for (let i = 0; i < 100; i++) {
+      world.simulate(16);
+    }
+    expect(startCount).toBe(countAfterLanding);
+  });
+
+  it('should fire onCollisionEnd when a body is knocked away and separates', () => {
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+
+    const ball = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
+      { position: { x: 0, y: -20 } },
+    );
+    ball.addToWorld({ physicsWorld: world } as any);
+    ball.linearVelocity = { x: 0, y: 10 };
+    ball.nativeBody.frictionAir = 0;
+
+    let endEvents: (MatterRigidBodyComponent | null)[] = [];
+    ball.onCollisionEnd.subscribe(e => endEvents.push(e));
+
+    for (let i = 0; i < 200 && endEvents.length === 0; i++) {
+      world.simulate(16);
+      if (i === 50) {
+        // knock it straight back up, away from the floor, once it's had a chance to touch
+        ball.linearVelocity = { x: 0, y: -10 };
+      }
+    }
+
+    expect(endEvents.length).toBeGreaterThan(0);
+    expect(endEvents[0]).toBe(floor);
+  });
+
+  it('should emit onCollisionEnd(null) on the remaining body when the other body is removed from the world while still touching', () => {
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+
+    const ball = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
+      { position: { x: 0, y: -20 } },
+    );
+    ball.addToWorld({ physicsWorld: world } as any);
+    ball.linearVelocity = { x: 0, y: 10 };
+    ball.nativeBody.frictionAir = 0;
+
+    let floorEndEvents: (MatterRigidBodyComponent | null)[] = [];
+    floor.onCollisionEnd.subscribe(e => floorEndEvents.push(e));
+    let ballStarted = false;
+    ball.onCollisionStart.subscribe(() => (ballStarted = true));
+
+    for (let i = 0; i < 200 && !ballStarted; i++) {
+      world.simulate(16);
+    }
+    expect(ballStarted).toBe(true);
+    expect(floorEndEvents.length).toBe(0);
+
+    ball.removeFromWorld({ physicsWorld: world } as any);
+    expect(floorEndEvents.length).toBe(1);
+    expect(floorEndEvents[0]).toBeNull();
+  });
+
+  it('should not fire the rigid body onCollisionStart for a trigger overlapping a rigid body', () => {
+    const trigger = factory.createTrigger({ shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, { position: { x: 0, y: 0 } });
+    trigger.addToWorld({ physicsWorld: world } as any);
+
+    const ball = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
+      { position: { x: 0, y: -20 } },
+    );
+    ball.addToWorld({ physicsWorld: world } as any);
+    ball.linearVelocity = { x: 0, y: 10 };
+    ball.nativeBody.frictionAir = 0;
+
+    let ballStartEvents = 0;
+    let triggerEnterEvents = 0;
+    ball.onCollisionStart.subscribe(() => ballStartEvents++);
+    trigger.onEntityEntered.subscribe(() => triggerEnterEvents++);
+
+    for (let i = 0; i < 200; i++) {
+      world.simulate(16);
+    }
+
+    expect(triggerEnterEvents).toBeGreaterThan(0);
+    expect(ballStartEvents).toBe(0);
+  });
+});

package/test/components/matter-world.component.spec.ts

@@ -18,13 +18,14 @@ describe('MatterWorldComponent', () => {
   });
 
   describe('Rigid bodies', () => {
-
     it('should simulate inertial motion of rigid body', () => {
-
-      const circle = world.factory.createRigidBody({
-        shape: { shape: 'CIRCLE', radius: 1 },
-        body: { dynamic: true, mass: 5 },
-      }, { position: { x: -5, y: 0 } });
+      const circle = world.factory.createRigidBody(
+        {
+          shape: { shape: 'CIRCLE', radius: 1 },
+          body: { dynamic: true, mass: 5 },
+        },
+        { position: { x: -5, y: 0 } },
+      );
       circle.addToWorld({ physicsWorld: world } as any);
       circle.linearVelocity = { x: 1, y: 0 };
       circle.nativeBody.frictionAir = 0;
@@ -37,19 +38,24 @@ describe('MatterWorldComponent', () => {
     });
 
     it('should simulate collision of two rigid bodies', () => {
-
-      const circle0 = world.factory.createRigidBody({
-        shape: { shape: 'CIRCLE', radius: 1 },
-        body: { dynamic: true, mass: 5 },
-      }, { position: { x: -5, y: 0 } });
+      const circle0 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'CIRCLE', radius: 1 },
+          body: { dynamic: true, mass: 5 },
+        },
+        { position: { x: -5, y: 0 } },
+      );
       circle0.addToWorld({ physicsWorld: world } as any);
       circle0.linearVelocity = { x: 1, y: 0 };
       circle0.nativeBody.frictionAir = 0;
 
-      const circle1 = world.factory.createRigidBody({
-        shape: { shape: 'CIRCLE', radius: 1 },
-        body: { dynamic: true, mass: 5 },
-      }, { position: { x: 5, y: 0 } });
+      const circle1 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'CIRCLE', radius: 1 },
+          body: { dynamic: true, mass: 5 },
+        },
+        { position: { x: 5, y: 0 } },
+      );
       circle1.addToWorld({ physicsWorld: world } as any);
       circle1.linearVelocity = { x: -1, y: 0 };
       circle1.nativeBody.frictionAir = 0;
@@ -62,22 +68,42 @@ describe('MatterWorldComponent', () => {
       expect(circle1.position.x).toBeGreaterThan(0);
     });
 
+    it('keeps handleIdEntityMap (the O(1) findRigidBody lookup) in sync with children on add/remove', () => {
+      const circle = world.factory.createRigidBody(
+        { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
+        { position: { x: 0, y: 0 } },
+      );
+      circle.addToWorld({ physicsWorld: world } as any);
+
+      expect(world.handleIdEntityMap.get(circle.nativeBody.id)).toBe(circle);
+
+      circle.removeFromWorld({ physicsWorld: world } as any);
+
+      expect(world.handleIdEntityMap.has(circle.nativeBody.id)).toBe(false);
+    });
+
     it('should not simulate collision of two rigid bodies with different collision groups', () => {
       const cg0 = world.registerCollisionGroup();
-      const circle0 = world.factory.createRigidBody({
-        shape: { shape: 'CIRCLE', radius: 1 },
-        body: { dynamic: true, mass: 5 },
-      }, { position: { x: -5, y: 0 } });
+      const circle0 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'CIRCLE', radius: 1 },
+          body: { dynamic: true, mass: 5 },
+        },
+        { position: { x: -5, y: 0 } },
+      );
       circle0.addToWorld({ physicsWorld: world } as any);
       circle0.linearVelocity = { x: 1, y: 0 };
       circle0.nativeBody.frictionAir = 0;
       circle0.ownCollisionGroups = circle0.interactWithCollisionGroups = [cg0];
 
       const cg1 = world.registerCollisionGroup();
-      const circle1 = world.factory.createRigidBody({
-        shape: { shape: 'CIRCLE', radius: 1 },
-        body: { dynamic: true, mass: 5 },
-      }, { position: { x: 5, y: 0 } });
+      const circle1 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'CIRCLE', radius: 1 },
+          body: { dynamic: true, mass: 5 },
+        },
+        { position: { x: 5, y: 0 } },
+      );
       circle1.addToWorld({ physicsWorld: world } as any);
       circle1.linearVelocity = { x: -1, y: 0 };
       circle1.nativeBody.frictionAir = 0;
@@ -93,13 +119,15 @@ describe('MatterWorldComponent', () => {
   });
 
   describe.skip('Raycast', () => {
-
     it('should return no hit when ray does not intersect any object', () => {
       // Create a square far away from the ray
-      const square = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
-        body: { dynamic: false, mass: 0 },
-      }, { position: { x: 10, y: 10 } });
+      const square = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
+          body: { dynamic: false, mass: 0 },
+        },
+        { position: { x: 10, y: 10 } },
+      );
       square.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -119,10 +147,13 @@ describe('MatterWorldComponent', () => {
 
     it('should detect hit when ray intersects an object', () => {
       // Create a square in the path of the ray
-      const square = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
-        body: { dynamic: false, mass: 0 },
-      }, { position: { x: 0, y: -5 } });
+      const square = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
+          body: { dynamic: false, mass: 0 },
+        },
+        { position: { x: 0, y: -5 } },
+      );
       square.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -153,15 +184,18 @@ describe('MatterWorldComponent', () => {
       const group2 = world.registerCollisionGroup();
 
       // Create a square that only belongs to group1
-      const square1 = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
-        body: {
-          dynamic: false,
-          mass: 0,
-          ownCollisionGroups: [group1],
-          interactWithCollisionGroups: [group1, group2],
+      const square1 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
+          body: {
+            dynamic: false,
+            mass: 0,
+            ownCollisionGroups: [group1],
+            interactWithCollisionGroups: [group1, group2],
+          },
         },
-      }, { position: { x: 0, y: -5 } });
+        { position: { x: 0, y: -5 } },
+      );
       square1.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -192,10 +226,13 @@ describe('MatterWorldComponent', () => {
 
     it('should calculate hit distance correctly', () => {
       // Create a square at a known distance
-      const square = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
-        body: { dynamic: false, mass: 0 },
-      }, { position: { x: 0, y: -5 } });
+      const square = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
+          body: { dynamic: false, mass: 0 },
+        },
+        { position: { x: 0, y: -5 } },
+      );
       square.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -220,15 +257,18 @@ describe('MatterWorldComponent', () => {
       const group2 = world.registerCollisionGroup();
 
       // Create a square that belongs to group1
-      const square = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
-        body: {
-          dynamic: false,
-          mass: 0,
-          ownCollisionGroups: [group1],
-          interactWithCollisionGroups: [group1, group2],
+      const square = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
+          body: {
+            dynamic: false,
+            mass: 0,
+            ownCollisionGroups: [group1],
+            interactWithCollisionGroups: [group1, group2],
+          },
         },
-      }, { position: { x: 0, y: -5 } });
+        { position: { x: 0, y: -5 } },
+      );
       square.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -247,16 +287,22 @@ describe('MatterWorldComponent', () => {
 
     it('should return correct hit body', () => {
       // Create two squares at different positions
-      const square1 = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
-        body: { dynamic: false, mass: 0 },
-      }, { position: { x: 0, y: -3 } });
+      const square1 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
+          body: { dynamic: false, mass: 0 },
+        },
+        { position: { x: 0, y: -3 } },
+      );
       square1.addToWorld({ physicsWorld: world } as any);
 
-      const square2 = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
-        body: { dynamic: false, mass: 0 },
-      }, { position: { x: 0, y: -7 } });
+      const square2 = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
+          body: { dynamic: false, mass: 0 },
+        },
+        { position: { x: 0, y: -7 } },
+      );
       square2.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -275,10 +321,13 @@ describe('MatterWorldComponent', () => {
 
     it('should handle edge case with ray starting inside an object', () => {
       // Create a square
-      const square = world.factory.createRigidBody({
-        shape: { shape: 'SQUARE', dimensions: { x: 4, y: 4 } },
-        body: { dynamic: false, mass: 0 },
-      }, { position: { x: 0, y: 0 } });
+      const square = world.factory.createRigidBody(
+        {
+          shape: { shape: 'SQUARE', dimensions: { x: 4, y: 4 } },
+          body: { dynamic: false, mass: 0 },
+        },
+        { position: { x: 0, y: 0 } },
+      );
       square.addToWorld({ physicsWorld: world } as any);
 
       world.simulate(1);
@@ -298,4 +347,4 @@ describe('MatterWorldComponent', () => {
       expect(result).toBeDefined();
     });
   });
-});
+});