@gg-web-engine/matter 0.0.71 → 0.0.73

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

@@ -1,19 +1,47 @@
 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>;
+    /** `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;
     constructor(nativeBody: Body, shape: Shape2DDescriptor, world: MatterWorldComponent);
@@ -23,6 +51,20 @@ 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;
+    /**
+     * Regular rigid-body overlaps are handled entirely by `handleCollisionStart`/`handleCollisionEnd`
+     * above, off matter's own native `collisionStart`/`collisionEnd` engine events - so this used to be
+     * a pure no-op for matter-js. 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;
     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,8 @@ 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.add(comp);
                     this.onEnter$.next(comp);
                 }
             }
@@ -37,7 +39,8 @@ 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.delete(comp);
                     this.onLeft$.next(comp);
                 }
             }
@@ -49,6 +52,11 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         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();
@@ -73,14 +81,33 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         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)) {
+                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();
+        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 +118,51 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         this.onLeft$.complete();
         super.dispose();
     }
+    /**
+     * Regular rigid-body overlaps are handled entirely by `handleCollisionStart`/`handleCollisionEnd`
+     * above, off matter's own native `collisionStart`/`collisionEnd` engine events - so this used to be
+     * a pure no-op for matter-js. 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
+        // `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);
+            }
+        }
     }
     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,19 +5,23 @@ 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);
@@ -54,6 +58,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 {};

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

@@ -7,10 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Pnt2, } from '@gg-web-engine/core';
-import { Engine, Events } from 'matter-js';
+import { BitMask, Pnt2, } from '@gg-web-engine/core';
+import { Composite, Detector, Engine, Events } from 'matter-js';
 import { MatterFactory } from '../matter-factory';
 import { Subject } from 'rxjs';
+import { MatterRigidBodyComponent } from './matter-rigid-body.component';
 /**
  * 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
@@ -34,6 +35,42 @@ function averageSupports(collision) {
     }
     return Pnt2.scalarMult(sum, 1 / supports.length);
 }
+/**
+ * Standard 2D segment-vs-segment intersection (parametric form): `p1->p2` is the ray segment,
+ * `p3->p4` one polygon edge. Returns the intersection's fractional position along `p1->p2`
+ * (`t`, always in `[0,1]` when a result is returned) and the world-space point itself, or `null`
+ * for parallel/non-intersecting/out-of-range segments. Used by `MatterWorldComponent.raycast`
+ * (see its own doc for why) instead of matter-js's own `Query.ray`/`Collision.collides`, which
+ * only ever reports an approximate SAT contact point, not a true point where the ray segment
+ * crosses a candidate's actual boundary.
+ */
+function segmentIntersection(p1, p2, p3, p4) {
+    const d1 = Pnt2.sub(p2, p1);
+    const d2 = Pnt2.sub(p4, p3);
+    const denom = d1.x * d2.y - d1.y * d2.x;
+    if (Math.abs(denom) < 1e-10) {
+        return null; // parallel (or degenerate) - no single intersection point
+    }
+    const diff = Pnt2.sub(p3, p1);
+    const t = (diff.x * d2.y - diff.y * d2.x) / denom;
+    const u = (diff.x * d1.y - diff.y * d1.x) / denom;
+    if (t < 0 || t > 1 || u < 0 || u > 1) {
+        return null;
+    }
+    return { t, point: Pnt2.add(p1, Pnt2.scalarMult(d1, t)) };
+}
+/**
+ * Every polygon (in matter-js's sense) making up `body`'s actual collision boundary, each as a
+ * closed loop of world-space vertices - `body` itself for a simple (non-compound) body, or every
+ * part but the synthetic index-0 "container" part for a compound one (mirrors `Query.collides`'s
+ * own `partsAStart = partsALength === 1 ? 0 : 1` convention). A circle is included via matter-js's
+ * own many-sided-polygon approximation (`Bodies.circle` is built on `Bodies.polygon`) - close
+ * enough for a raycast headroom check, not a true circle intersection.
+ */
+function bodyPolygons(body) {
+    const parts = body.parts.length === 1 ? [body] : body.parts.slice(1);
+    return parts.map(part => part.vertices);
+}
 // TODO probably should be configurable in world
 const MATTER_WORLD_SCALE = 0.0001;
 export class MatterWorldComponent {
@@ -61,7 +98,9 @@ export class MatterWorldComponent {
         /** 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. */
+         * 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. */
         this.handleIdEntityMap = new Map();
         this._gravity = { x: 0, y: 9.82 };
         this.mainCollisionGroup = 0;
@@ -89,7 +128,11 @@ export class MatterWorldComponent {
         });
     }
     findRigidBody(nativeBody) {
-        return this.handleIdEntityMap.get(nativeBody.id);
+        // a character controller's phantom body is never added to `Composite`/`engine.world` (see its
+        // own doc), so it can never actually be `pair.bodyA`/`pair.bodyB` here - this narrows the lookup's
+        // type back down since `handleIdEntityMap` itself now also tracks that component class.
+        const comp = this.handleIdEntityMap.get(nativeBody.id);
+        return comp instanceof MatterRigidBodyComponent ? comp : undefined;
     }
     /**
      * Wires `IRigidBody2dComponent.onCollisionStart` for every non-sensor pair in the world, off
@@ -173,8 +216,79 @@ export class MatterWorldComponent {
         Engine.update(this.matterEngine, delta, this.lastDelta > 0 ? delta / this.lastDelta : 1);
         this.lastDelta = delta;
     }
+    /**
+     * 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) {
-        throw new Error('Ray casting is not implemented for Matter.js');
+        var _a;
+        const matterWorld = this.matterWorld;
+        const direction = Pnt2.sub(options.to, options.from);
+        const rayLength = Pnt2.len(direction);
+        if (!matterWorld || rayLength === 0) {
+            return { hasHit: false };
+        }
+        const groupsMask = options.collisionFilterGroups
+            ? BitMask.pack(options.collisionFilterGroups, 16)
+            : BitMask.full(16);
+        const maskMask = options.collisionFilterMask ? BitMask.pack(options.collisionFilterMask, 16) : BitMask.full(16);
+        const rayFilter = { category: groupsMask, mask: maskMask, group: 0 };
+        const candidates = Composite.allBodies(matterWorld).filter(b => !b.isSensor && Detector.canCollide(rayFilter, b.collisionFilter));
+        let closestT = Infinity;
+        let closestPoint = null;
+        let closestNormal = null;
+        let closestBody = null;
+        for (const body of candidates) {
+            for (const polygon of bodyPolygons(body)) {
+                for (let i = 0; i < polygon.length; i++) {
+                    const a = polygon[i];
+                    const b = polygon[(i + 1) % polygon.length];
+                    const hit = segmentIntersection(options.from, options.to, a, b);
+                    if (!hit || hit.t >= closestT) {
+                        continue;
+                    }
+                    closestT = hit.t;
+                    closestPoint = hit.point;
+                    closestBody = body;
+                    const edge = Pnt2.sub(b, a);
+                    const normal = Pnt2.norm({ x: -edge.y, y: edge.x });
+                    closestNormal = Pnt2.dot(normal, Pnt2.sub(options.from, hit.point)) >= 0 ? normal : Pnt2.neg(normal);
+                }
+            }
+        }
+        if (!closestBody) {
+            return { hasHit: false };
+        }
+        // A compound body's hit part is not the parent body `handleIdEntityMap` is keyed by (see
+        // `MatterFactory`'s compound-shape flattening) - `.parent` (self-referential for a non-compound
+        // body) resolves back to it.
+        const parentBody = (_a = closestBody.parent) !== null && _a !== void 0 ? _a : closestBody;
+        const resolved = this.handleIdEntityMap.get(parentBody.id);
+        return {
+            hasHit: true,
+            hitBody: resolved instanceof MatterRigidBodyComponent ? resolved : undefined,
+            hitDistance: closestT * rayLength,
+            hitPoint: closestPoint,
+            hitNormal: closestNormal,
+        };
     }
     dispose() {
         Events.off(this.matterEngine, 'collisionStart', this.handleCollisionStart);

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './components/matter-character-controller.component';
 export * from './components/matter-rigid-body.component';
 export * from './components/matter-trigger.component';
 export * from './components/matter-world.component';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './components/matter-character-controller.component';
 export * from './components/matter-rigid-body.component';
 export * from './components/matter-trigger.component';
 export * from './components/matter-world.component';

package/dist/matter-factory.d.ts

@@ -1,6 +1,7 @@
-import { BodyShape2DDescriptor, IPhysicsBody2dComponentFactory, Point2, Shape2DDescriptor } from '@gg-web-engine/core';
+import { BodyShape2DDescriptor, CharacterController2dOptions, IPhysicsBody2dComponentFactory, Point2, Shape2DDescriptor } from '@gg-web-engine/core';
 import { MatterRigidBodyComponent } from './components/matter-rigid-body.component';
 import { MatterTriggerComponent } from './components/matter-trigger.component';
+import { MatterCharacterControllerComponent } from './components/matter-character-controller.component';
 import { MatterWorldComponent } from './components/matter-world.component';
 import { MatterPhysicsTypeDocRepo } from './types';
 export declare class MatterFactory implements IPhysicsBody2dComponentFactory<MatterPhysicsTypeDocRepo> {
@@ -14,6 +15,12 @@ export declare class MatterFactory implements IPhysicsBody2dComponentFactory<Mat
         position?: Point2;
         rotation?: number;
     }): MatterTriggerComponent;
+    createCharacterController(options: CharacterController2dOptions, transform?: {
+        position?: Point2;
+        rotation?: number;
+    }): MatterCharacterControllerComponent;
+    private createShapeParts;
+    private createShapeBody;
     /**
      * matter-js's own body model only has `isStatic` - no distinct kinematic body type (position-
      * driven, but still pushes/wakes dynamic bodies it moves into) and no continuous collision

package/dist/matter-factory.js

@@ -1,7 +1,17 @@
-import { warnOnce, } from '@gg-web-engine/core';
+import { Pnt2, warnOnce, } from '@gg-web-engine/core';
 import { MatterRigidBodyComponent } from './components/matter-rigid-body.component';
 import { MatterTriggerComponent } from './components/matter-trigger.component';
-import { Bodies, Vector } from 'matter-js';
+import { MatterCharacterControllerComponent } from './components/matter-character-controller.component';
+import { Bodies, Body, Common, Vector } from 'matter-js';
+import * as decomp from 'poly-decomp';
+/**
+ * `Bodies.fromVertices` (used for the `POLYGON` shape below) only actually decomposes a concave
+ * vertex set into convex parts when a decomposition library is registered via `Common.setDecomp` -
+ * without it, matter-js silently falls back to the convex hull of the given vertices, so a concave
+ * `POLYGON` would render/collide as if it were convex. Registering `poly-decomp` here, once, at
+ * module load makes `Bodies.fromVertices` actually decompose concave outlines everywhere it's used.
+ */
+Common.setDecomp(decomp);
 /**
  * `kinematic_pos`/`kinematic_vel`/`ccd` have no native matter-js equivalent at all - unlike
  * `packages/ammo`/`packages/rapier2d`/`packages/rapier3d`, this package can only warn and fall
@@ -19,45 +29,140 @@ export class MatterFactory {
         this.world = world;
     }
     createRigidBody(descriptor, transform) {
-        var _a, _b;
+        var _a, _b, _c;
         let nativeBody = null;
         switch (descriptor.shape.shape) {
-            case 'SQUARE':
+            case 'BOX':
                 nativeBody = Bodies.rectangle(0, 0, descriptor.shape.dimensions.x, descriptor.shape.dimensions.y, this.transformOptions(descriptor.body));
                 break;
             case 'CIRCLE':
                 nativeBody = Bodies.circle(0, 0, descriptor.shape.radius, this.transformOptions(descriptor.body));
                 break;
+            case 'CAPSULE':
+                nativeBody = Bodies.rectangle(0, 0, descriptor.shape.radius * 2, descriptor.shape.centersDistance + descriptor.shape.radius * 2, {
+                    chamfer: {
+                        radius: descriptor.shape.radius,
+                    },
+                });
+                break;
+            case 'CONVEX_HULL':
+                nativeBody = Bodies.fromVertices(0, 0, [Pnt2.hull(descriptor.shape.vertices).map(v => Vector.create(v.x, v.y))], this.transformOptions(descriptor.body));
+                break;
+            case 'POLYGON':
+                nativeBody = Bodies.fromVertices(0, 0, [descriptor.shape.vertices.map(v => Vector.create(v.x, v.y))], this.transformOptions(descriptor.body));
+                break;
+            case 'COMPOUND':
+                nativeBody = this.createShapeBody(descriptor.shape, this.transformOptions(descriptor.body));
+                break;
         }
         if (!nativeBody) {
             throw new Error(`Shape "${descriptor.shape}" not implemented for Matter.js`);
         }
-        nativeBody.position = Vector.create(((_a = transform === null || transform === void 0 ? void 0 : transform.position) === null || _a === void 0 ? void 0 : _a.x) || 0, ((_b = transform === null || transform === void 0 ? void 0 : transform.position) === null || _b === void 0 ? void 0 : _b.y) || 0);
-        nativeBody.angle = (transform === null || transform === void 0 ? void 0 : transform.rotation) || 0;
-        return new MatterRigidBodyComponent(nativeBody, descriptor.shape);
+        // Must go through `Body.setPosition`/`Body.setAngle` (not a raw `nativeBody.position = ...`
+        // field assignment) - see `gg-engine-physics-adapter-matter`'s own note on this: a body's
+        // `vertices`/`bounds` (what every actual collision query reads) are only ever translated to
+        // match `.position` at creation time, using whatever position was passed into
+        // `Bodies.rectangle`/`Bodies.circle`/`Bodies.fromVertices` itself (always `(0, 0)` here) - a
+        // later raw field write changes what `.position` *reports* without moving the real collision
+        // geometry at all, permanently desyncing the two until something else (ordinary simulation,
+        // which this character-controller-adjacent code path can't rely on) happens to correct it.
+        Body.setPosition(nativeBody, Vector.create(((_a = transform === null || transform === void 0 ? void 0 : transform.position) === null || _a === void 0 ? void 0 : _a.x) || 0, ((_b = transform === null || transform === void 0 ? void 0 : transform.position) === null || _b === void 0 ? void 0 : _b.y) || 0));
+        Body.setAngle(nativeBody, (transform === null || transform === void 0 ? void 0 : transform.rotation) || 0);
+        const bodyType = (_c = descriptor.body.bodyType) !== null && _c !== void 0 ? _c : (descriptor.body.mass ? 'dynamic' : 'static');
+        const component = new MatterRigidBodyComponent(nativeBody, descriptor.shape, bodyType, !!descriptor.body.ccd);
+        // `transformOptions` (used to build `nativeBody` above) only ever reads
+        // `bodyType`/`mass`/`restitution`/`friction` - `ownCollisionGroups`/`interactWithCollisionGroups`
+        // must be applied through the component's own setters afterward (same as
+        // `MatterCharacterControllerComponent`'s constructor already does for a character), or a
+        // configured collision group is silently dropped in favor of the "all groups" default every
+        // `MatterRigidBodyComponent` otherwise starts with.
+        if (descriptor.body.ownCollisionGroups !== undefined) {
+            component.ownCollisionGroups = descriptor.body.ownCollisionGroups;
+        }
+        if (descriptor.body.interactWithCollisionGroups !== undefined) {
+            component.interactWithCollisionGroups = descriptor.body.interactWithCollisionGroups;
+        }
+        return component;
     }
     createTrigger(descriptor, transform) {
         var _a, _b;
         let nativeBody = null;
         switch (descriptor.shape) {
-            case 'SQUARE':
+            case 'BOX':
                 nativeBody = Bodies.rectangle(0, 0, descriptor.dimensions.x, descriptor.dimensions.y, { isSensor: true });
                 break;
             case 'CIRCLE':
                 nativeBody = Bodies.circle(0, 0, descriptor.radius, { isSensor: true });
                 break;
+            case 'CAPSULE':
+                nativeBody = Bodies.rectangle(0, 0, descriptor.radius * 2, descriptor.centersDistance + descriptor.radius * 2, {
+                    isSensor: true,
+                    chamfer: {
+                        radius: descriptor.radius,
+                    },
+                });
+                break;
+            case 'CONVEX_HULL':
+                nativeBody = Bodies.fromVertices(0, 0, [Pnt2.hull(descriptor.vertices).map(v => Vector.create(v.x, v.y))], {
+                    isSensor: true,
+                });
+                break;
+            case 'POLYGON':
+                nativeBody = Bodies.fromVertices(0, 0, [descriptor.vertices.map(v => Vector.create(v.x, v.y))], {
+                    isSensor: true,
+                });
+                break;
+            case 'COMPOUND':
+                nativeBody = this.createShapeBody(descriptor, { isSensor: true });
+                break;
         }
         if (!nativeBody) {
             throw new Error(`Shape "${descriptor.shape}" not implemented for Matter.js`);
         }
-        nativeBody.position.x = ((_a = transform === null || transform === void 0 ? void 0 : transform.position) === null || _a === void 0 ? void 0 : _a.x) || 0;
-        nativeBody.position.y = ((_b = transform === null || transform === void 0 ? void 0 : transform.position) === null || _b === void 0 ? void 0 : _b.y) || 0;
-        nativeBody.angle = (transform === null || transform === void 0 ? void 0 : transform.rotation) || 0;
+        // See the identical fix (and its doc) in `createRigidBody` above - a trigger's collision
+        // geometry needs the same real `Body.setPosition`/`Body.setAngle` treatment, not a raw
+        // `.position.x`/`.position.y`/`.angle` field write.
+        Body.setPosition(nativeBody, Vector.create(((_a = transform === null || transform === void 0 ? void 0 : transform.position) === null || _a === void 0 ? void 0 : _a.x) || 0, ((_b = transform === null || transform === void 0 ? void 0 : transform.position) === null || _b === void 0 ? void 0 : _b.y) || 0));
+        Body.setAngle(nativeBody, (transform === null || transform === void 0 ? void 0 : transform.rotation) || 0);
         if (!this.world) {
             throw new Error('MatterFactory: World not set. Make sure the factory is created by MatterWorldComponent.');
         }
         return new MatterTriggerComponent(nativeBody, descriptor, this.world);
     }
+    createCharacterController(options, transform) {
+        return new MatterCharacterControllerComponent(this.world, options, transform);
+    }
+    createShapeParts(shape, options) {
+        switch (shape.shape) {
+            case 'BOX':
+                return [Bodies.rectangle(0, 0, shape.dimensions.x, shape.dimensions.y, options)];
+            case 'CIRCLE':
+                return [Bodies.circle(0, 0, shape.radius, options)];
+            case 'CAPSULE':
+                return [
+                    Bodies.rectangle(0, 0, shape.radius * 2, shape.centersDistance + shape.radius * 2, Object.assign(Object.assign({}, options), { chamfer: { radius: shape.radius } })),
+                ];
+            case 'CONVEX_HULL':
+                return [Bodies.fromVertices(0, 0, [Pnt2.hull(shape.vertices).map(v => Vector.create(v.x, v.y))], options)];
+            case 'POLYGON':
+                return [Bodies.fromVertices(0, 0, [shape.vertices.map(v => Vector.create(v.x, v.y))], options)];
+            case 'COMPOUND': {
+                const parts = [];
+                for (const { position, rotation, shape: childShape } of shape.children) {
+                    const childParts = this.createShapeParts(childShape, options);
+                    for (const part of childParts) {
+                        Body.setPosition(part, Vector.add(Vector.rotate(part.position, rotation || 0), Vector.create((position === null || position === void 0 ? void 0 : position.x) || 0, (position === null || position === void 0 ? void 0 : position.y) || 0)));
+                        Body.setAngle(part, part.angle + (rotation || 0));
+                    }
+                    parts.push(...childParts);
+                }
+                return parts;
+            }
+        }
+    }
+    createShapeBody(shape, options) {
+        return Body.create(Object.assign({ parts: this.createShapeParts(shape, options) }, options));
+    }
     /**
      * matter-js's own body model only has `isStatic` - no distinct kinematic body type (position-
      * driven, but still pushes/wakes dynamic bodies it moves into) and no continuous collision

package/dist/types.d.ts

@@ -1,12 +1,14 @@
 import { MatterFactory } from './matter-factory';
 import { MatterRigidBodyComponent } from './components/matter-rigid-body.component';
 import { MatterTriggerComponent } from './components/matter-trigger.component';
+import { MatterCharacterControllerComponent } from './components/matter-character-controller.component';
 import { Gg2dWorld, Gg2dWorldSceneTypeDocPPatch, Gg2dWorldTypeDocPPatch } from '@gg-web-engine/core';
 import { MatterWorldComponent } from './components/matter-world.component';
 export type MatterPhysicsTypeDocRepo = {
     factory: MatterFactory;
     rigidBody: MatterRigidBodyComponent;
     trigger: MatterTriggerComponent;
+    characterController: MatterCharacterControllerComponent;
 };
 export type MatterTypeDoc = Gg2dWorldTypeDocPPatch<MatterPhysicsTypeDocRepo>;
 export type MatterSceneTypeDoc = Gg2dWorldSceneTypeDocPPatch<MatterPhysicsTypeDocRepo, MatterWorldComponent>;