@gg-web-engine/matter 0.0.77 → 0.0.78

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

@@ -7,6 +7,7 @@ export declare class MatterRigidBodyComponent implements IRigidBody2dComponent<M
     readonly shape: Shape2DDescriptor;
     readonly bodyType: BodyType;
     readonly ccd: boolean;
+    readonly canSleep: boolean;
     get position(): Point2;
     set position(value: Point2);
     get rotation(): number;
@@ -43,7 +44,7 @@ export declare class MatterRigidBodyComponent implements IRigidBody2dComponent<M
      * `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, bodyType?: BodyType, ccd?: boolean);
+    constructor(nativeBody: Body, shape: Shape2DDescriptor, bodyType?: BodyType, ccd?: boolean, canSleep?: boolean);
     /** @internal called by `MatterWorldComponent`'s global `collisionStart` listener - not part of
      * this component's public API surface. */
     notifyCollisionStart(collisionEvent: CollisionEvent<Point2, MatterRigidBodyComponent>): void;
@@ -80,7 +81,8 @@ export declare class MatterRigidBodyComponent implements IRigidBody2dComponent<M
      */
     wakeUp(): void;
     /**
-     * No-op on a body that reports `isStatic` (see `isSleeping`'s own doc). Forces sleep immediately,
+     * No-op on a body that reports `isStatic` (see `isSleeping`'s own doc) or was created with
+     * `canSleep: false`. 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.

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

@@ -1,5 +1,17 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import { BitMask, DebugBody2DSettings, Pnt2, } from '@gg-web-engine/core';
 import { Body, Composite, Sleeping, Vector } from 'matter-js';
+import { buildMatterRigidBody } from '../matter-rigid-body-builder';
 import { Subject } from 'rxjs';
 // FIXME why this needs to be introduced? investigate units in matter.js
 const MATTER_VELOCITY_SCALE = 0.0166667;
@@ -47,6 +59,7 @@ export class MatterRigidBodyComponent {
             friction: this.nativeBody.friction,
             restitution: this.nativeBody.restitution,
             ccd: this.ccd,
+            canSleep: this.canSleep,
             ownCollisionGroups: this.ownCollisionGroups,
             interactWithCollisionGroups: this.interactWithCollisionGroups,
         };
@@ -57,11 +70,12 @@ export class MatterRigidBodyComponent {
     get onCollisionEnd() {
         return this.onCollisionEnd$.asObservable();
     }
-    constructor(nativeBody, shape, bodyType = 'dynamic', ccd = false) {
+    constructor(nativeBody, shape, bodyType = 'dynamic', ccd = false, canSleep = true) {
         this.nativeBody = nativeBody;
         this.shape = shape;
         this.bodyType = bodyType;
         this.ccd = ccd;
+        this.canSleep = canSleep;
         this.name = '';
         this.entity = null;
         // matter-js has no native kinematic body - a body requested as `kinematic_pos`/`kinematic_vel`
@@ -83,6 +97,11 @@ export class MatterRigidBodyComponent {
          * world-wide `collisionStart`/`collisionEnd` listener - not touched directly by anything else. */
         this.currentContacts = new Set();
         this.updateCollisionFilter();
+        if (!canSleep) {
+            // this adapter's engine never sleeps bodies on its own, but an app may turn on
+            // `engine.enableSleeping` - an infinite threshold keeps this body awake even then
+            nativeBody.sleepThreshold = Infinity;
+        }
     }
     /** @internal called by `MatterWorldComponent`'s global `collisionStart` listener - not part of
      * this component's public API surface. */
@@ -134,11 +153,15 @@ export class MatterRigidBodyComponent {
         this.nativeBody.collisionFilter = Object.assign(Object.assign({}, this.nativeBody.collisionFilter), { category: this._ownCGsMask, mask: this._interactWithCGsMask });
     }
     clone() {
-        const clonedBody = Body.create(Object.assign(Object.assign({}, this.nativeBody), { collisionFilter: Object.assign({}, this.nativeBody.collisionFilter) }));
-        const component = new MatterRigidBodyComponent(clonedBody, this.shape, this.bodyType, this.ccd);
-        component.ownCollisionGroups = this.ownCollisionGroups;
-        component.interactWithCollisionGroups = this.interactWithCollisionGroups;
-        return component;
+        // Rebuilt from the shape and options rather than `Body.create({ ...this.nativeBody })`: a native
+        // body references itself (`parts[0]` and `parent` are the body itself), so matter-js's deep
+        // option merge recurses forever on it.
+        const _a = this.bodyOptions, { mass } = _a, options = __rest(_a, ["mass"]);
+        return buildMatterRigidBody({
+            shape: this.shape,
+            // a static body reports an infinite mass, which isn't a valid option to build one from
+            body: this.bodyType === 'dynamic' ? Object.assign(Object.assign({}, options), { mass }) : options,
+        }, { position: this.position, rotation: this.rotation });
     }
     addToWorld(world) {
         Composite.add(world.physicsWorld.matterWorld, this.nativeBody);
@@ -199,13 +222,14 @@ export class MatterRigidBodyComponent {
         Sleeping.set(this.nativeBody, false);
     }
     /**
-     * No-op on a body that reports `isStatic` (see `isSleeping`'s own doc). Forces sleep immediately,
+     * No-op on a body that reports `isStatic` (see `isSleeping`'s own doc) or was created with
+     * `canSleep: false`. 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) {
+        if (this.nativeBody.isStatic || !this.canSleep) {
             return;
         }
         Sleeping.set(this.nativeBody, true);

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

@@ -1,6 +1,7 @@
 import { map, merge, Subject } from 'rxjs';
 import { Body, Detector, Events, Query } from 'matter-js';
 import { MatterRigidBodyComponent } from './matter-rigid-body.component';
+import { buildMatterTriggerBody } from '../matter-rigid-body-builder';
 import { MatterCharacterControllerComponent } from './matter-character-controller.component';
 import { DebugBody2DSettings } from '@gg-web-engine/core';
 export class MatterTriggerComponent extends MatterRigidBodyComponent {
@@ -230,7 +231,8 @@ export class MatterTriggerComponent extends MatterRigidBodyComponent {
         }
     }
     clone() {
-        const clonedBody = Body.create(Object.assign(Object.assign({}, this.nativeBody), { isSensor: true, collisionFilter: Object.assign({}, this.nativeBody.collisionFilter) }));
+        // rebuilt from the shape, for the same reason as in `MatterRigidBodyComponent.clone()`
+        const clonedBody = buildMatterTriggerBody(this.shape, { position: this.position, rotation: this.rotation });
         const component = new MatterTriggerComponent(clonedBody, this.shape, this.world);
         component.ownCollisionGroups = this.ownCollisionGroups;
         component.interactWithCollisionGroups = this.interactWithCollisionGroups;

package/dist/matter-factory.d.ts

@@ -19,20 +19,4 @@ export declare class MatterFactory implements IPhysicsBody2dComponentFactory<Mat
         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
-     * detection at all, at any level. Both are long-standing, documented upstream limitations, not
-     * something this adapter package failed to wire up - see `BodyOptions.kinematic_pos`/
-     * `ccd`'s own doc in `packages/core` for what each is supposed to do.
-     *
-     * `kinematic_pos`/`kinematic_vel` fall back to `isStatic: true` - the closest matter-js has - so
-     * a caller gets *a* body rather than a thrown error, but with the exact same caveat as
-     * teleporting a `static` body's position by hand (see that doc): resting bodies on top won't be
-     * pushed or woken correctly. `ccd: true` is silently accepted as a no-op beyond the warning below -
-     * a fast-moving or fast-driven body can still tunnel clean through thin geometry in one step.
-     */
-    private transformOptions;
 }

package/dist/matter-factory.js

@@ -1,203 +1,20 @@
-import { Pnt2, warnOnce, } 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 { 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
- * back rather than actually implement either (see `transformOptions`'s own doc). Warned once per
- * distinct message (via core's `warnOnce`) rather than once per body/tick - an app that spawns many
- * kinematic props (or requests `ccd` on many fast-moving bodies) would otherwise flood the console
- * with an identical warning on every single one, which teaches a developer to ignore the console
- * rather than to fix the one call site that needs it.
- */
-function warnUnsupportedOnce(message) {
-    warnOnce(`[@gg-web-engine/matter] ${message}`);
-}
+import { buildMatterRigidBody, buildMatterTriggerBody } from './matter-rigid-body-builder';
 export class MatterFactory {
     constructor(world) {
         this.world = world;
     }
     createRigidBody(descriptor, transform) {
-        var _a, _b, _c;
-        let nativeBody = null;
-        switch (descriptor.shape.shape) {
-            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`);
-        }
-        // 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;
+        return buildMatterRigidBody(descriptor, transform);
     }
     createTrigger(descriptor, transform) {
-        var _a, _b;
-        let nativeBody = null;
-        switch (descriptor.shape) {
-            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`);
-        }
-        // 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);
+        return new MatterTriggerComponent(buildMatterTriggerBody(descriptor, transform), 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
-     * detection at all, at any level. Both are long-standing, documented upstream limitations, not
-     * something this adapter package failed to wire up - see `BodyOptions.kinematic_pos`/
-     * `ccd`'s own doc in `packages/core` for what each is supposed to do.
-     *
-     * `kinematic_pos`/`kinematic_vel` fall back to `isStatic: true` - the closest matter-js has - so
-     * a caller gets *a* body rather than a thrown error, but with the exact same caveat as
-     * teleporting a `static` body's position by hand (see that doc): resting bodies on top won't be
-     * pushed or woken correctly. `ccd: true` is silently accepted as a no-op beyond the warning below -
-     * a fast-moving or fast-driven body can still tunnel clean through thin geometry in one step.
-     */
-    transformOptions(options) {
-        if (options.bodyType === 'kinematic_pos' || options.bodyType === 'kinematic_vel') {
-            warnUnsupportedOnce(`bodyType: '${options.bodyType}' has no matter-js equivalent - falling back to a plain static ` +
-                "body. Resting bodies won't be pushed or woken when you move it, the same as manually " +
-                "teleporting a static body's position. See Body2DOptions.kinematic_pos/kinematic_vel's doc.");
-        }
-        if (options.ccd) {
-            warnUnsupportedOnce('ccd: true has no matter-js equivalent (no continuous collision detection at all) - ignored. ' +
-                'A fast-moving or fast-driven body can still tunnel through thin geometry. See ' +
-                "Body2DOptions.ccd's doc.");
-        }
-        const res = {
-            isStatic: options.bodyType !== undefined ? options.bodyType != 'dynamic' : !options.mass,
-            mass: options.mass,
-            restitution: options.restitution,
-            friction: options.friction,
-        };
-        for (const key in res) {
-            if (res[key] === undefined) {
-                delete res[key];
-            }
-        }
-        return res;
-    }
 }

package/dist/matter-rigid-body-builder.d.ts

@@ -0,0 +1,24 @@
+import { BodyShape2DDescriptor, Point2, Shape2DDescriptor } from '@gg-web-engine/core';
+import { Body, IChamferableBodyDefinition } from 'matter-js';
+import { MatterRigidBodyComponent } from './components/matter-rigid-body.component';
+/**
+ * Builds a rigid body for `MatterFactory.createRigidBody`. A plain function because building one
+ * never needs the world (it's added to one later, in `addToWorld`), which lets
+ * `MatterRigidBodyComponent.clone()` rebuild its body from its own shape and options without a
+ * factory instance at hand, and without importing the factory module: that module imports
+ * `MatterTriggerComponent`, which extends `MatterRigidBodyComponent`, so importing it from the
+ * rigid body's own module is a circular import that breaks the `extends`.
+ */
+export declare function buildMatterRigidBody(descriptor: BodyShape2DDescriptor, transform?: {
+    position?: Point2;
+    rotation?: number;
+}): MatterRigidBodyComponent;
+export declare function createShapeBody(shape: Shape2DDescriptor, options: IChamferableBodyDefinition): Body;
+/**
+ * Builds the sensor body of a trigger, for `MatterFactory.createTrigger` and
+ * `MatterTriggerComponent.clone()`.
+ */
+export declare function buildMatterTriggerBody(shape: Shape2DDescriptor, transform?: {
+    position?: Point2;
+    rotation?: number;
+}): Body;

package/dist/matter-rigid-body-builder.js

@@ -0,0 +1,168 @@
+import { Pnt2, warnOnce, } from '@gg-web-engine/core';
+import { Bodies, Body, Common, Vector } from 'matter-js';
+import * as decomp from 'poly-decomp';
+import { MatterRigidBodyComponent } from './components/matter-rigid-body.component';
+/**
+ * `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
+ * back rather than actually implement either (see `transformOptions`'s own doc). Warned once per
+ * distinct message (via core's `warnOnce`) rather than once per body/tick - an app that spawns many
+ * kinematic props (or requests `ccd` on many fast-moving bodies) would otherwise flood the console
+ * with an identical warning on every single one, which teaches a developer to ignore the console
+ * rather than to fix the one call site that needs it.
+ */
+function warnUnsupportedOnce(message) {
+    warnOnce(`[@gg-web-engine/matter] ${message}`);
+}
+/**
+ * Builds a rigid body for `MatterFactory.createRigidBody`. A plain function because building one
+ * never needs the world (it's added to one later, in `addToWorld`), which lets
+ * `MatterRigidBodyComponent.clone()` rebuild its body from its own shape and options without a
+ * factory instance at hand, and without importing the factory module: that module imports
+ * `MatterTriggerComponent`, which extends `MatterRigidBodyComponent`, so importing it from the
+ * rigid body's own module is a circular import that breaks the `extends`.
+ */
+export function buildMatterRigidBody(descriptor, transform) {
+    var _a, _b, _c;
+    let nativeBody = null;
+    switch (descriptor.shape.shape) {
+        case 'BOX':
+            nativeBody = Bodies.rectangle(0, 0, descriptor.shape.dimensions.x, descriptor.shape.dimensions.y, transformOptions(descriptor.body));
+            break;
+        case 'CIRCLE':
+            nativeBody = Bodies.circle(0, 0, descriptor.shape.radius, transformOptions(descriptor.body));
+            break;
+        case 'CAPSULE':
+            nativeBody = Bodies.rectangle(0, 0, descriptor.shape.radius * 2, descriptor.shape.centersDistance + descriptor.shape.radius * 2, Object.assign(Object.assign({}, transformOptions(descriptor.body)), { 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))], transformOptions(descriptor.body));
+            break;
+        case 'POLYGON':
+            nativeBody = Bodies.fromVertices(0, 0, [descriptor.shape.vertices.map(v => Vector.create(v.x, v.y))], transformOptions(descriptor.body));
+            break;
+        case 'COMPOUND':
+            nativeBody = createShapeBody(descriptor.shape, transformOptions(descriptor.body));
+            break;
+    }
+    if (!nativeBody) {
+        throw new Error(`Shape "${descriptor.shape}" not implemented for Matter.js`);
+    }
+    // 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, descriptor.body.canSleep !== false);
+    // `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;
+}
+function 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 = 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;
+        }
+    }
+}
+export function createShapeBody(shape, options) {
+    return Body.create(Object.assign({ parts: createShapeParts(shape, options) }, options));
+}
+/**
+ * Builds the sensor body of a trigger, for `MatterFactory.createTrigger` and
+ * `MatterTriggerComponent.clone()`.
+ */
+export function buildMatterTriggerBody(shape, transform) {
+    var _a, _b;
+    const options = { isSensor: true };
+    const nativeBody = shape.shape === 'COMPOUND' ? createShapeBody(shape, options) : createShapeParts(shape, options)[0];
+    // `Body.setPosition`/`Body.setAngle` rather than raw field writes, for the same reason as in
+    // `buildMatterRigidBody` above
+    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);
+    return nativeBody;
+}
+/**
+ * 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
+ * detection at all, at any level. Both are long-standing, documented upstream limitations, not
+ * something this adapter package failed to wire up - see `BodyOptions.kinematic_pos`/
+ * `ccd`'s own doc in `packages/core` for what each is supposed to do.
+ *
+ * `kinematic_pos`/`kinematic_vel` fall back to `isStatic: true` - the closest matter-js has - so
+ * a caller gets *a* body rather than a thrown error, but with the exact same caveat as
+ * teleporting a `static` body's position by hand (see that doc): resting bodies on top won't be
+ * pushed or woken correctly. `ccd: true` is silently accepted as a no-op beyond the warning below -
+ * a fast-moving or fast-driven body can still tunnel clean through thin geometry in one step.
+ */
+function transformOptions(options) {
+    if (options.bodyType === 'kinematic_pos' || options.bodyType === 'kinematic_vel') {
+        warnUnsupportedOnce(`bodyType: '${options.bodyType}' has no matter-js equivalent - falling back to a plain static ` +
+            "body. Resting bodies won't be pushed or woken when you move it, the same as manually " +
+            "teleporting a static body's position. See Body2DOptions.kinematic_pos/kinematic_vel's doc.");
+    }
+    if (options.ccd) {
+        warnUnsupportedOnce('ccd: true has no matter-js equivalent (no continuous collision detection at all) - ignored. ' +
+            'A fast-moving or fast-driven body can still tunnel through thin geometry. See ' +
+            "Body2DOptions.ccd's doc.");
+    }
+    const res = {
+        isStatic: options.bodyType !== undefined ? options.bodyType != 'dynamic' : !options.mass,
+        mass: options.mass,
+        restitution: options.restitution,
+        friction: options.friction,
+    };
+    for (const key in res) {
+        if (res[key] === undefined) {
+            delete res[key];
+        }
+    }
+    return res;
+}

package/package.json

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

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

@@ -76,4 +76,17 @@ describe('MatterRigidBodyComponent sleep API', () => {
     floor.wakeUp();
     expect(floor.isSleeping).toBe(false);
   });
+
+  it('a canSleep: false body ignores sleep() and keeps that option through clone()', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1, canSleep: false } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    body.sleep();
+    expect(body.isSleeping).toBe(false);
+    expect(body.bodyOptions.canSleep).toBe(false);
+    expect(body.clone().bodyOptions.canSleep).toBe(false);
+  });
 });

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

@@ -96,3 +96,108 @@ describe('MatterRigidBodyComponent.rotation', () => {
     expect(height).toBeCloseTo(2);
   });
 });
+
+describe('MatterRigidBodyComponent.clone', () => {
+  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('copies shape, transform and body options into an independent native body', () => {
+    const body = factory.createRigidBody(
+      {
+        shape: { shape: 'BOX', dimensions: { x: 2, y: 1 } },
+        body: { bodyType: 'dynamic', mass: 5, friction: 0.3, restitution: 0.7, canSleep: false },
+      },
+      { position: { x: 3, y: 4 }, rotation: 0.5 },
+    );
+    body.ownCollisionGroups = [2];
+    body.interactWithCollisionGroups = [3];
+
+    const clone = body.clone();
+
+    expect(clone.nativeBody).not.toBe(body.nativeBody);
+    expect(clone.shape).toEqual(body.shape);
+    expect(clone.position.x).toBeCloseTo(3);
+    expect(clone.position.y).toBeCloseTo(4);
+    expect(clone.rotation).toBeCloseTo(0.5);
+    expect(clone.bodyOptions).toEqual(body.bodyOptions);
+
+    clone.position = { x: 10, y: 10 };
+    expect(body.position.x).toBeCloseTo(3);
+  });
+
+  it('clones a body that is already in a world, and the clone can be added too', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    const clone = body.clone();
+    clone.addToWorld({ physicsWorld: world } as any);
+
+    expect(world.matterWorld!.bodies).toContain(clone.nativeBody);
+    expect(world.matterWorld!.bodies).toContain(body.nativeBody);
+  });
+
+  it('keeps a static body static', () => {
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 10, y: 1 } }, body: { bodyType: 'static' } },
+      { position: { x: 0, y: 5 } },
+    );
+
+    const clone = floor.clone();
+
+    expect(clone.nativeBody.isStatic).toBe(true);
+    expect(clone.bodyOptions.bodyType).toBe('static');
+  });
+
+  it('clones a compound body', () => {
+    const body = factory.createRigidBody(
+      {
+        shape: {
+          shape: 'COMPOUND',
+          children: [
+            { shape: { shape: 'BOX', dimensions: { x: 1, y: 1 } }, position: { x: -1, y: 0 } },
+            { shape: { shape: 'CIRCLE', radius: 0.5 }, position: { x: 1, y: 0 } },
+          ],
+        },
+        body: { bodyType: 'dynamic', mass: 2 },
+      },
+      { position: { x: 0, y: 0 } },
+    );
+
+    const clone = body.clone();
+
+    expect(clone.nativeBody.parts.length).toBe(body.nativeBody.parts.length);
+    expect(clone.bodyOptions.mass).toBeCloseTo(2);
+  });
+});
+
+describe('MatterFactory capsule rigid body', () => {
+  it('applies body options to a capsule, like every other shape', async () => {
+    const world = new MatterWorldComponent();
+    await world.init();
+    const capsule = new MatterFactory(world).createRigidBody(
+      { shape: { shape: 'CAPSULE', radius: 0.5, centersDistance: 1 }, body: { bodyType: 'dynamic', mass: 3, friction: 0.2 } },
+      { position: { x: 0, y: 0 } },
+    );
+
+    expect(capsule.nativeBody.mass).toBeCloseTo(3);
+    expect(capsule.nativeBody.friction).toBe(0.2);
+    world.dispose();
+  });
+});

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

@@ -250,4 +250,46 @@ describe(`MatterTriggerComponent`, () => {
     await Promise.resolve();
     expect(exitRegistered).toBe(true);
   });
+
+  it(`clones into an independent sensor of the same shape, transform and collision groups`, () => {
+    const trigger = factory.createTrigger(
+      { shape: 'BOX', dimensions: { x: 10, y: 4 } },
+      { position: { x: 3, y: 4 }, rotation: 0.5 },
+    );
+    trigger.ownCollisionGroups = [2];
+    trigger.interactWithCollisionGroups = [3];
+    trigger.addToWorld({ physicsWorld: world } as any);
+
+    const clone = trigger.clone();
+
+    expect(clone.nativeBody).not.toBe(trigger.nativeBody);
+    expect(clone.nativeBody.isSensor).toBe(true);
+    expect(clone.nativeBody.isStatic).toBe(true);
+    expect(clone.shape).toEqual(trigger.shape);
+    expect(clone.position.x).toBeCloseTo(3);
+    expect(clone.position.y).toBeCloseTo(4);
+    expect(clone.rotation).toBeCloseTo(0.5);
+    expect(clone.ownCollisionGroups).toEqual([2]);
+    expect(clone.interactWithCollisionGroups).toEqual([3]);
+
+    clone.addToWorld({ physicsWorld: world } as any);
+    expect(world.matterWorld!.bodies).toContain(clone.nativeBody);
+    clone.position = { x: 10, y: 10 };
+    expect(trigger.position.x).toBeCloseTo(3);
+  });
+
+  it(`clones a compound trigger`, () => {
+    const trigger = factory.createTrigger({
+      shape: 'COMPOUND',
+      children: [
+        { shape: { shape: 'BOX', dimensions: { x: 2, y: 2 } } },
+        { position: { x: 3, y: 0 }, shape: { shape: 'CIRCLE', radius: 1 } },
+      ],
+    });
+
+    const clone = trigger.clone();
+
+    expect(clone.nativeBody.parts.length).toBe(trigger.nativeBody.parts.length);
+    expect(clone.nativeBody.isSensor).toBe(true);
+  });
 });