@gg-web-engine/matter 0.0.72 → 0.0.74

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

@@ -1,5 +1,5 @@
 import { BitMask, DebugBody2DSettings, Pnt2, } from '@gg-web-engine/core';
-import { Body, Composite, Vector } from 'matter-js';
+import { Body, Composite, Sleeping, 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;
@@ -14,7 +14,7 @@ export class MatterRigidBodyComponent {
         return this.nativeBody.angle;
     }
     set rotation(value) {
-        this.nativeBody.angle = value;
+        Body.setAngle(this.nativeBody, value);
     }
     get linearVelocity() {
         return Pnt2.scalarMult(this.nativeBody.velocity, 1 / MATTER_VELOCITY_SCALE);
@@ -28,15 +28,40 @@ export class MatterRigidBodyComponent {
     set angularVelocity(value) {
         Body.setAngularVelocity(this.nativeBody, value);
     }
+    /**
+     * See `IRigidBodyComponent.bodyOptions`'s own doc. `mass`/`friction`/`restitution` are read live
+     * off the native matter-js body (a plain JS object - `.mass`/`.friction`/`.restitution` are
+     * ordinary fields, resolved to matter-js's own defaults by `Body.create` for whichever of them
+     * weren't explicitly given, so this reflects the body's *actual* resolved values, not just
+     * whatever was requested). `bodyType`/`ccd` are stored as originally requested rather than
+     * derived from the native body: matter-js has no kinematic body concept at all (a requested
+     * `kinematic_pos`/`kinematic_vel` degrades to a plain `isStatic` body - see `MatterFactory
+     * .transformOptions`'s own doc) and no CCD, so neither is recoverable from - or even meaningfully
+     * "live" on - the native body itself; echoing the request instead keeps a level JSON reloaded
+     * under a different, kinematic/CCD-capable adapter faithful to what was actually asked for.
+     */
+    get bodyOptions() {
+        return {
+            bodyType: this.bodyType,
+            mass: this.nativeBody.mass,
+            friction: this.nativeBody.friction,
+            restitution: this.nativeBody.restitution,
+            ccd: this.ccd,
+            ownCollisionGroups: this.ownCollisionGroups,
+            interactWithCollisionGroups: this.interactWithCollisionGroups,
+        };
+    }
     get onCollisionStart() {
         return this.onCollisionStart$.asObservable();
     }
     get onCollisionEnd() {
         return this.onCollisionEnd$.asObservable();
     }
-    constructor(nativeBody, shape) {
+    constructor(nativeBody, shape, bodyType = 'dynamic', ccd = false) {
         this.nativeBody = nativeBody;
         this.shape = shape;
+        this.bodyType = bodyType;
+        this.ccd = ccd;
         this.name = '';
         this.entity = null;
         // matter-js has no native kinematic body - a body requested as `kinematic_pos`/`kinematic_vel`
@@ -45,7 +70,7 @@ export class MatterRigidBodyComponent {
         // rather than what an app originally asked for - the console warning at creation time is what
         // tells a developer their kinematic request wasn't honored, not this view.
         this.debugBodySettings = new DebugBody2DSettings(isFinite(this.nativeBody.mass)
-            ? { type: 'RIGID_DYNAMIC', sleeping: () => this.nativeBody.isSleeping }
+            ? { type: 'RIGID_DYNAMIC', sleeping: () => this.isSleeping }
             : { type: 'RIGID_STATIC' }, this.shape);
         this._interactWithCGsMask = BitMask.full(16);
         this._ownCGsMask = BitMask.full(16);
@@ -110,7 +135,7 @@ export class MatterRigidBodyComponent {
     }
     clone() {
         const clonedBody = Body.create(Object.assign(Object.assign({}, this.nativeBody), { collisionFilter: Object.assign({}, this.nativeBody.collisionFilter) }));
-        const component = new MatterRigidBodyComponent(clonedBody, this.shape);
+        const component = new MatterRigidBodyComponent(clonedBody, this.shape, this.bodyType, this.ccd);
         component.ownCollisionGroups = this.ownCollisionGroups;
         component.interactWithCollisionGroups = this.interactWithCollisionGroups;
         return component;
@@ -147,4 +172,42 @@ export class MatterRigidBodyComponent {
         Body.setVelocity(this.nativeBody, Pnt2.O);
         Body.setAngularVelocity(this.nativeBody, 0);
     }
+    /**
+     * A `kinematic_pos`/`kinematic_vel` request also reports `isStatic: true` here - see this
+     * component's own `bodyType`/`bodyOptions` doc for why matter-js can't distinguish that from a
+     * genuine `'static'` body natively. Both are equally never simulated as a sleepable dynamic body,
+     * so gating on the native `isStatic` flag rather than `this.bodyType === 'static'` is correct for
+     * both cases, not just the literal static one.
+     *
+     * Also always `false` regardless of `isStatic` unless the world's underlying `Matter.Engine` was
+     * created with `enableSleeping: true` - this adapter never turns that on itself (see
+     * `MatterWorldComponent`'s own doc on its `matterWorld`/engine setup), so a body constructed
+     * through this adapter alone never actually falls asleep on its own; `sleep()` below still forces
+     * it regardless of that engine setting.
+     */
+    get isSleeping() {
+        return !this.nativeBody.isStatic && this.nativeBody.isSleeping;
+    }
+    /**
+     * No-op on a body that reports `isStatic` (a genuine `'static'` body, or a `kinematic_pos`/
+     * `kinematic_vel` request - see `isSleeping`'s own doc for why both are treated the same here).
+     */
+    wakeUp() {
+        if (this.nativeBody.isStatic) {
+            return;
+        }
+        Sleeping.set(this.nativeBody, false);
+    }
+    /**
+     * No-op on a body that reports `isStatic` (see `isSleeping`'s own doc). Forces sleep immediately,
+     * regardless of whether the world's `Matter.Engine` has `enableSleeping` turned on - unlike a
+     * body naturally falling asleep from inactivity (which requires that engine flag), an explicit
+     * `Sleeping.set(body, true)` call takes effect either way.
+     */
+    sleep() {
+        if (this.nativeBody.isStatic) {
+            return;
+        }
+        Sleeping.set(this.nativeBody, true);
+    }
 }

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

@@ -1,21 +1,61 @@
 import { Observable, Subject } from 'rxjs';
 import { Body } from 'matter-js';
 import { MatterRigidBodyComponent } from './matter-rigid-body.component';
+import { MatterCharacterControllerComponent } from './matter-character-controller.component';
 import { DebugBody2DSettings, ITrigger2dComponent, Shape2DDescriptor } from '@gg-web-engine/core';
 import { MatterWorldComponent } from './matter-world.component';
 import { MatterGgWorld, MatterPhysicsTypeDocRepo } from '../types';
 export declare class MatterTriggerComponent extends MatterRigidBodyComponent implements ITrigger2dComponent<MatterPhysicsTypeDocRepo> {
     readonly shape: Shape2DDescriptor;
     protected readonly world: MatterWorldComponent;
-    get onEntityEntered(): Observable<MatterRigidBodyComponent>;
-    get onEntityLeft(): Observable<MatterRigidBodyComponent>;
-    protected readonly onEnter$: Subject<MatterRigidBodyComponent>;
-    protected readonly onLeft$: Subject<MatterRigidBodyComponent>;
+    get onEntityEntered(): Observable<MatterRigidBodyComponent | MatterCharacterControllerComponent>;
+    get onEntityLeft(): Observable<MatterRigidBodyComponent | MatterCharacterControllerComponent>;
+    protected readonly onEnter$: Subject<MatterRigidBodyComponent | MatterCharacterControllerComponent>;
+    protected readonly onLeft$: Subject<MatterRigidBodyComponent | MatterCharacterControllerComponent>;
+    /** Character controllers currently overlapping this trigger, as of the last `checkOverlaps()`
+     * poll - see that method's own doc for why this needs its own separate polling mechanism instead
+     * of the native `collisionStart`/`collisionEnd` events `handleCollisionStart`/`handleCollisionEnd`
+     * below rely on for ordinary rigid bodies. */
+    protected currentCharacterOverlaps: Set<MatterCharacterControllerComponent>;
     readonly debugBodySettings: DebugBody2DSettings;
     protected intersectionsAmount: number;
     protected currentOverlaps: Set<MatterRigidBodyComponent>;
+    /** The subset of `currentOverlaps` whose exit `checkOverlaps()` detects by polling, because matter's
+     * detector doesn't pair them with this (static) trigger body - see {@link isPolled}. A body moves
+     * back to the native-event path once a native `collisionStart` reports it (it woke up inside). */
+    protected polledOverlaps: Set<MatterRigidBodyComponent>;
+    /** `Composite.remove` (what `removeFromWorld` calls) never fires a native `collisionEnd` for the
+     * body it removes - matter-js simply stops considering that body's pairs on the next step, it
+     * doesn't retroactively report the pairs that were active at removal time. Without this, a body
+     * removed from the world while still overlapping this trigger would leave `currentOverlaps`
+     * (and, for a character, `currentCharacterOverlaps`) permanently stale and `onEntityLeft` would
+     * never fire for it. `world.physicsWorld.removed$` fires for every component removal regardless
+     * of overlap state, so this only actually acts when the removed component is one this trigger was
+     * still tracking as an overlap.
+     *
+     * The stale entry is dropped synchronously, but `onLeft$` itself is only ever emitted on a
+     * microtask from this reaction, never inline. `removed$` fires from inside whatever call stack
+     * performed the removal - which can be another component's own in-progress lifecycle operation:
+     * `CharacterController2dEntity.recreateCapsule()` (crouch/stand) removes the *old*
+     * `characterController` with `dispose: true` before it has assigned the new one, so an `onLeft$`
+     * subscriber running inline there (app code driven by `Trigger2dEntity`, e.g. a kill volume
+     * resetting `.position` on the character that just left it) would write through the old,
+     * already-removed `MatterCharacterControllerComponent` - `Body.setPosition` on a body no longer
+     * queried by anything - and the write is silently lost, with the replacement capsule then spawning
+     * at the stale position. Deferring the emission keeps it within the same JS turn (well before the
+     * next `Engine.update`) but strictly after every synchronous call stack in flight, including the
+     * removal's own, has unwound. */
+    private removedSub?;
     private handleCollisionStart;
     private handleCollisionEnd;
+    /**
+     * Whether matter's detector never pairs `comp` with this trigger: it skips every pair whose bodies
+     * are both static or sleeping, and the trigger body is static. That covers sleeping bodies and
+     * kinematic ones (built as static here, see `MatterFactory`). Bodies requested as `'static'` are
+     * level geometry and are never reported.
+     */
+    protected isPolled(comp: MatterRigidBodyComponent): boolean;
+    protected overlaps(comp: MatterRigidBodyComponent): boolean;
     constructor(nativeBody: Body, shape: Shape2DDescriptor, world: MatterWorldComponent);
     addToWorld(world: MatterGgWorld): void;
     removeFromWorld(world: MatterGgWorld, dispose?: boolean): void;
@@ -23,6 +63,28 @@ export declare class MatterTriggerComponent extends MatterRigidBodyComponent imp
      * `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;
+    /**
+     * Awake dynamic bodies are handled by `handleCollisionStart`/`handleCollisionEnd` above, off
+     * matter's own native `collisionStart`/`collisionEnd` engine events; kinematic and sleeping ones,
+     * which matter never pairs with this static body, are polled by `checkPolledBodyOverlaps()`.
+     * A `MatterCharacterControllerComponent`'s own phantom body is
+     * deliberately never added to `Composite`/`engine.world` at all (see that class's own doc), so no
+     * native collision pair - and thus no native event - can ever involve it. Since `checkOverlaps()` is
+     * already called once per tick by `Trigger2dEntity` regardless of backend, this is the natural place
+     * to add the poll this needs instead of inventing a second, differently-shaped mechanism: every
+     * `MatterCharacterControllerComponent` currently in the world (`world.children`, which - unlike
+     * matter's own `Composite` - already tracks it) is tested against this trigger's own body via
+     * `Query.collides`, diffed against `currentCharacterOverlaps` to fire `onEntityEntered`/
+     * `onEntityLeft` exactly on the enter/exit transitions, the same as the native-event path does for
+     * ordinary bodies.
+     */
     checkOverlaps(): void;
+    /**
+     * Enter/exit of the rigid bodies matter's detector never pairs with this trigger (see
+     * {@link isPolled}): a kinematic platform moving in or out, a body asleep inside. Like the
+     * character poll below, `Query.collides` ignores `collisionFilter`, so `Detector.canCollide` is
+     * checked by hand.
+     */
+    protected checkPolledBodyOverlaps(): void;
     clone(): MatterTriggerComponent;
 }

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

@@ -1,6 +1,7 @@
 import { map, merge, Subject } from 'rxjs';
-import { Body, Events } from 'matter-js';
+import { Body, Detector, Events, Query } from 'matter-js';
 import { MatterRigidBodyComponent } from './matter-rigid-body.component';
+import { MatterCharacterControllerComponent } from './matter-character-controller.component';
 import { DebugBody2DSettings } from '@gg-web-engine/core';
 export class MatterTriggerComponent extends MatterRigidBodyComponent {
     get onEntityEntered() {
@@ -20,7 +21,13 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
             }
             if (body) {
                 let comp = this.world.children.find(c => c.nativeBody === body);
-                if (comp) {
+                if (comp instanceof MatterRigidBodyComponent) {
+                    if (this.currentOverlaps.has(comp)) {
+                        // already inside via polling (it was asleep or kinematic): the native pair takes over
+                        this.polledOverlaps.delete(comp);
+                        continue;
+                    }
+                    this.currentOverlaps.add(comp);
                     this.onEnter$.next(comp);
                 }
             }
@@ -37,22 +44,56 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
             }
             if (body) {
                 let comp = this.world.children.find(c => c.nativeBody === body);
-                if (comp) {
+                if (comp instanceof MatterRigidBodyComponent && this.currentOverlaps.has(comp)) {
+                    if (this.isPolled(comp) && this.overlaps(comp)) {
+                        // a body falling asleep inside: matter drops the pair without it having left
+                        this.polledOverlaps.add(comp);
+                        continue;
+                    }
+                    this.currentOverlaps.delete(comp);
+                    this.polledOverlaps.delete(comp);
                     this.onLeft$.next(comp);
                 }
             }
         }
     }
+    /**
+     * Whether matter's detector never pairs `comp` with this trigger: it skips every pair whose bodies
+     * are both static or sleeping, and the trigger body is static. That covers sleeping bodies and
+     * kinematic ones (built as static here, see `MatterFactory`). Bodies requested as `'static'` are
+     * level geometry and are never reported.
+     */
+    isPolled(comp) {
+        return comp.bodyType === 'kinematic_pos' || comp.bodyType === 'kinematic_vel' || comp.nativeBody.isSleeping;
+    }
+    overlaps(comp) {
+        return Query.collides(this.nativeBody, [comp.nativeBody]).length > 0;
+    }
     constructor(nativeBody, shape, world) {
         super(nativeBody, shape);
         this.shape = shape;
         this.world = world;
         this.onEnter$ = new Subject();
         this.onLeft$ = new Subject();
+        /** Character controllers currently overlapping this trigger, as of the last `checkOverlaps()`
+         * poll - see that method's own doc for why this needs its own separate polling mechanism instead
+         * of the native `collisionStart`/`collisionEnd` events `handleCollisionStart`/`handleCollisionEnd`
+         * below rely on for ordinary rigid bodies. */
+        this.currentCharacterOverlaps = new Set();
         this.debugBodySettings = new DebugBody2DSettings({ type: 'TRIGGER', activated: () => this.intersectionsAmount > 0 }, this.shape);
         this.intersectionsAmount = 0;
         this.currentOverlaps = new Set();
+        /** The subset of `currentOverlaps` whose exit `checkOverlaps()` detects by polling, because matter's
+         * detector doesn't pair them with this (static) trigger body - see {@link isPolled}. A body moves
+         * back to the native-event path once a native `collisionStart` reports it (it woke up inside). */
+        this.polledOverlaps = new Set();
         this.nativeBody.isSensor = true;
+        // A trigger is a fixed volume: left non-static, matter-js integrates its sensor body under
+        // gravity like any dynamic body, and since a sensor never collides it falls through the level
+        // (overlapping, and reporting, whatever it passes on the way down). Static also keeps
+        // static-static pairs (trigger vs level geometry) out of matter's broadphase entirely - which
+        // drops kinematic and sleeping bodies too, so `checkOverlaps()` polls those.
+        Body.setStatic(this.nativeBody, true);
         merge(this.onEnter$.pipe(map(() => true)), this.onLeft$.pipe(map(() => false))).subscribe(enter => {
             if (enter) {
                 this.intersectionsAmount++;
@@ -70,17 +111,39 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         }
         this.intersectionsAmount = 0;
         this.currentOverlaps.clear();
+        this.polledOverlaps.clear();
         super.addToWorld(world);
         Events.on(world.physicsWorld.matterEngine, 'collisionStart', this.handleCollisionStart);
         Events.on(world.physicsWorld.matterEngine, 'collisionEnd', this.handleCollisionEnd);
+        this.removedSub = world.physicsWorld.removed$.subscribe(c => {
+            if (c === this) {
+                return;
+            }
+            if (c instanceof MatterCharacterControllerComponent) {
+                if (this.currentCharacterOverlaps.delete(c)) {
+                    queueMicrotask(() => this.onLeft$.next(c));
+                }
+            }
+            else if (c instanceof MatterRigidBodyComponent && this.currentOverlaps.delete(c)) {
+                this.polledOverlaps.delete(c);
+                queueMicrotask(() => this.onLeft$.next(c));
+            }
+        });
     }
     removeFromWorld(world, dispose) {
+        var _a;
         Events.off(world.physicsWorld.matterEngine, 'collisionStart', this.handleCollisionStart);
         Events.off(world.physicsWorld.matterEngine, 'collisionEnd', this.handleCollisionEnd);
+        (_a = this.removedSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
         for (const body of this.currentOverlaps) {
             this.onLeft$.next(body);
         }
         this.currentOverlaps.clear();
+        this.polledOverlaps.clear();
+        for (const character of this.currentCharacterOverlaps) {
+            this.onLeft$.next(character);
+        }
+        this.currentCharacterOverlaps.clear();
         super.removeFromWorld(world, dispose);
     }
     /** Completes `onEnter$`/`onLeft$` on top of `MatterRigidBodyComponent.dispose()`'s own
@@ -91,8 +154,80 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         this.onLeft$.complete();
         super.dispose();
     }
+    /**
+     * Awake dynamic bodies are handled by `handleCollisionStart`/`handleCollisionEnd` above, off
+     * matter's own native `collisionStart`/`collisionEnd` engine events; kinematic and sleeping ones,
+     * which matter never pairs with this static body, are polled by `checkPolledBodyOverlaps()`.
+     * A `MatterCharacterControllerComponent`'s own phantom body is
+     * deliberately never added to `Composite`/`engine.world` at all (see that class's own doc), so no
+     * native collision pair - and thus no native event - can ever involve it. Since `checkOverlaps()` is
+     * already called once per tick by `Trigger2dEntity` regardless of backend, this is the natural place
+     * to add the poll this needs instead of inventing a second, differently-shaped mechanism: every
+     * `MatterCharacterControllerComponent` currently in the world (`world.children`, which - unlike
+     * matter's own `Composite` - already tracks it) is tested against this trigger's own body via
+     * `Query.collides`, diffed against `currentCharacterOverlaps` to fire `onEntityEntered`/
+     * `onEntityLeft` exactly on the enter/exit transitions, the same as the native-event path does for
+     * ordinary bodies.
+     */
     checkOverlaps() {
-        // do nothing, for matter.js we handle this differently
+        this.checkPolledBodyOverlaps();
+        // `Query.collides` tests raw geometry only and knows nothing about `collisionFilter` (see
+        // `MatterCharacterControllerComponent.collectObstacles`'s own doc on this same gap) - call
+        // matter's own `Detector.canCollide` directly so a character controller whose collision groups
+        // wouldn't ordinarily interact with this trigger isn't falsely reported entering it just because
+        // this poll bypasses the broadphase that would otherwise exclude it.
+        const characters = this.world.children.filter((c) => c instanceof MatterCharacterControllerComponent &&
+            Detector.canCollide(this.nativeBody.collisionFilter, c.nativeBody.collisionFilter));
+        const stillOverlapping = new Set();
+        if (characters.length > 0) {
+            const collisions = Query.collides(this.nativeBody, characters.map(c => c.nativeBody));
+            for (const collision of collisions) {
+                const otherNative = collision.parentA === this.nativeBody ? collision.parentB : collision.parentA;
+                const comp = characters.find(c => c.nativeBody === otherNative);
+                if (comp) {
+                    stillOverlapping.add(comp);
+                }
+            }
+        }
+        for (const comp of stillOverlapping) {
+            if (!this.currentCharacterOverlaps.has(comp)) {
+                this.currentCharacterOverlaps.add(comp);
+                this.onEnter$.next(comp);
+            }
+        }
+        for (const comp of this.currentCharacterOverlaps) {
+            if (!stillOverlapping.has(comp)) {
+                this.currentCharacterOverlaps.delete(comp);
+                this.onLeft$.next(comp);
+            }
+        }
+    }
+    /**
+     * Enter/exit of the rigid bodies matter's detector never pairs with this trigger (see
+     * {@link isPolled}): a kinematic platform moving in or out, a body asleep inside. Like the
+     * character poll below, `Query.collides` ignores `collisionFilter`, so `Detector.canCollide` is
+     * checked by hand.
+     */
+    checkPolledBodyOverlaps() {
+        for (const comp of this.world.children) {
+            if (comp instanceof MatterRigidBodyComponent &&
+                !(comp instanceof MatterTriggerComponent) &&
+                !this.currentOverlaps.has(comp) &&
+                this.isPolled(comp) &&
+                Detector.canCollide(this.nativeBody.collisionFilter, comp.nativeBody.collisionFilter) &&
+                this.overlaps(comp)) {
+                this.currentOverlaps.add(comp);
+                this.polledOverlaps.add(comp);
+                this.onEnter$.next(comp);
+            }
+        }
+        for (const comp of this.polledOverlaps) {
+            if (!this.overlaps(comp)) {
+                this.polledOverlaps.delete(comp);
+                this.currentOverlaps.delete(comp);
+                this.onLeft$.next(comp);
+            }
+        }
     }
     clone() {
         const clonedBody = Body.create(Object.assign(Object.assign({}, this.nativeBody), { isSensor: true, collisionFilter: Object.assign({}, this.nativeBody.collisionFilter) }));

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

@@ -5,24 +5,40 @@ import { MatterPhysicsTypeDocRepo } from '../types';
 import { Subject } from 'rxjs';
 import { MatterRigidBodyComponent } from './matter-rigid-body.component';
 import { MatterTriggerComponent } from './matter-trigger.component';
+import { MatterCharacterControllerComponent } from './matter-character-controller.component';
+type MatterWorldChild = MatterRigidBodyComponent | MatterTriggerComponent | MatterCharacterControllerComponent;
 export declare class MatterWorldComponent implements IPhysicsWorld2dComponent<MatterPhysicsTypeDocRepo> {
     protected matterEngine_: Engine | null;
     get matterEngine(): Engine | null;
     get matterWorld(): World | null;
     readonly factory: MatterFactory;
-    readonly added$: Subject<MatterRigidBodyComponent | MatterTriggerComponent>;
-    readonly removed$: Subject<MatterRigidBodyComponent | MatterTriggerComponent>;
-    readonly children: (MatterRigidBodyComponent | MatterTriggerComponent)[];
+    readonly added$: Subject<MatterWorldChild>;
+    readonly removed$: Subject<MatterWorldChild>;
+    readonly children: MatterWorldChild[];
     /** 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>;
+     * collision pair, per step - is an O(1) lookup instead of an O(n) `Array.find` scan. Also used by
+     * `MatterCharacterControllerComponent.pushDynamicBodies` to resolve a native body it just bumped
+     * into back to its owning component. */
+    readonly handleIdEntityMap: Map<number, MatterWorldChild>;
     private _gravity;
     get gravity(): Point2;
     set gravity(value: Point2);
     readonly mainCollisionGroup: CollisionGroup;
     constructor();
+    /**
+     * `Engine.create` is never given `enableSleeping: true` here, matching matter-js's own default -
+     * so a body this world creates never *naturally* falls asleep from prolonged inactivity, no matter
+     * how long it rests. `IRigidBodyComponent.sleep()`/`wakeUp()` still work regardless of this flag
+     * (`Matter.Sleeping.set` writes a body's `isSleeping` flag directly, and `Engine.update`'s own
+     * per-body integration skip checks that flag unconditionally, not gated behind
+     * `engine.enableSleeping` - only the *automatic* fall-asleep-from-rest/wake-on-collision behavior
+     * is gated behind that flag) - only automatic, inactivity-driven sleeping is unavailable under the
+     * current setup. A future change enabling it should re-check
+     * `gg-engine-physics-adapter-matter`'s own note on this before assuming every existing
+     * position/velocity setter still behaves the same way once bodies can sleep on their own.
+     */
     init(): Promise<void>;
     private findRigidBody;
     /**
@@ -54,6 +70,29 @@ export declare class MatterWorldComponent implements IPhysicsWorld2dComponent<Ma
     deregisterCollisionGroup(group: CollisionGroup): void;
     private lastDelta;
     simulate(delta: number): void;
+    /**
+     * matter-js has no native raycast query. Built on a true parametric ray-vs-polygon intersection
+     * (`segmentIntersection`/`bodyPolygons`), not `Matter.Query.ray` - that helper is only a thin
+     * wrapper over `Query.collides` (a full-geometry SAT test of a synthetic, very thin rectangle body
+     * against candidates), which reports an approximate overlap contact point, not a true "where does
+     * the ray segment first cross this body's boundary" point; verified via this adapter's own
+     * regression suite (`MatterWorldComponent.spec.ts`'s `Raycast` block expects a precise hit point at
+     * a known box edge) that the SAT-approximated version produces a visibly wrong point.
+     *
+     * `Query.collides`/`Collision.collides` test raw geometry only and know nothing about
+     * `collisionFilter` (the same limitation `MatterCharacterControllerComponent.collectObstacles`'s
+     * own doc describes) - candidates are pre-filtered here via `Detector.canCollide` itself, called
+     * directly against a synthetic filter built from `options.collisionFilterGroups`/
+     * `collisionFilterMask`. Sensor bodies (triggers) are excluded from candidates entirely, mirroring
+     * `collectObstacles`'s own exclusion - a trigger never physically blocks anything, so it shouldn't
+     * register as a raycast hit either.
+     *
+     * `hitNormal` is derived from whichever polygon edge the closest intersection landed on (rotated
+     * 90°, sign chosen to point back towards `options.from`) - not from a matter-js collision object at
+     * all, sidestepping the sign-convention pitfall `handleCollisionStart`'s own doc describes for
+     * `pair.collision.normal`.
+     */
     raycast(options: RaycastOptions<Point2>): RaycastResult<Point2, MatterRigidBodyComponent>;
     dispose(): void;
 }
+export {};