@combos-fun/plugin-matterjs 0.0.42 → 0.0.44

package/agent-skill.md

@@ -4,7 +4,7 @@
 
 ## When to read
 
-Read for any 2D physics task: gravity, collisions, kinematic / static bodies, mouse constraints, rigid-body alignment with sprites.
+Read for any 2D physics task: gravity, collisions, kinematic / static bodies, mouse constraints, rigid-body alignment with sprites, custom hulls (vertices / trapezoid / capsule / compound / edge / chain).
 
 ## Public API
 
@@ -13,24 +13,53 @@ import {
   PhysicsSystem,
   Physics,
   PhysicsType,
+  type PhysicsParams,
+  type PhysicsPartParams,
+  type PhysicsVertex,
   type PhysicsSystemParams,
 } from '@combos-fun/plugin-matterjs';
 ```
 
 ### `PhysicsType`
 
-`RECTANGLE`, `CIRCLE`, `POLYGON`.
+| Value | Matter mapping | Notes |
+|-------|----------------|-------|
+| `RECTANGLE` | `Bodies.rectangle` | Size = `width`/`height`, else `transform.size × scale` |
+| `CIRCLE` | `Bodies.circle` | `radius`; else `min(halfW, halfH)`, at least 1 |
+| `POLYGON` | `Bodies.polygon` | Regular n-gon. `sides` (min 3, default 6) + `radius` |
+| `TRAPEZOID` | `Bodies.trapezoid` | `width`/`height` (same fallback as rectangle) + `slope` (0–0.999, default 0.5) |
+| `FROM_VERTICES` | `Bodies.fromVertices` | Arbitrary polygon. Concave shapes are decomposed via `poly-decomp` |
+| `CAPSULE` | rectangle + 2 circles, then `Body.create({ parts })` | Stadium. `length` is full length including caps; `radius` is cap radius. `length <= 2r` becomes a circle |
+| `COMPOUND` | `Body.create({ parts })` | One rigid body from `parts[]`. Nested `COMPOUND` is rejected |
+| `EDGE` | thin `Bodies.rectangle` | Segment `from` → `to`. Orientation comes from the endpoints (not `bodyOptions.angle`) |
+| `CHAIN` | compound of thin rectangles | Rigid polyline through `vertices`. **Not** a soft rope |
+
+`CHAIN` / `EDGE` are static-terrain style colliders. A swinging rope needs multiple bodies + constraints; do not fake that with `CHAIN`.
+
+### Coordinates
+
+`vertices`, `vertexSets`, `from`, `to`, and each part's `position` are **local** to the GameObject centre. The factory adds the body origin (`bodyParams.position` or the object's transform). Do not pass world-space vertices.
 
 ### `Physics` Component params
 
 | Field | Type | Notes |
 |-------|------|-------|
-| `type` | `PhysicsType?` | Body shape |
-| `bodyOptions` | `object?` | Matter Body options: `isStatic`, `restitution`, `frictionAir`, `density`, `friction`, ... |
-| `position` | `{x, y}?` | Initial offset |
-| `sides` / `radius` | `number?` | Polygon / circle |
+| `type` | `PhysicsType?` | Body shape. Required when the object enters the scene |
+| `bodyOptions` | `object?` | Matter Body options: `isStatic`, `restitution`, `frictionAir`, `density`, `friction`, `angle`, ... |
+| `position` | `{x, y}?` | Body origin in world space. If omitted, taken from the GameObject transform |
+| `width` / `height` | `number?` | Rectangle / trapezoid / capsule fallback size |
+| `sides` / `radius` | `number?` | Regular polygon / circle / capsule cap |
+| `slope` | `number?` | Trapezoid only. Clamped to `< 1` |
+| `length` | `number?` | Capsule full length (including caps). Default = transform width |
+| `vertices` | `{x, y}[]?` | `FROM_VERTICES` (one contour) or `CHAIN` (polyline) |
+| `vertexSets` | `{x, y}[][]?` | `FROM_VERTICES` with multiple contours. Takes precedence over `vertices` |
+| `from` / `to` | `{x, y}?` | `EDGE` endpoints, local to the body origin |
+| `thickness` | `number?` | `EDGE` / `CHAIN` segment thickness. Default 4, minimum 1 |
+| `parts` | `PhysicsPartParams[]?` | `COMPOUND` only. Same shape fields as above, plus a local `position` offset. No nested `COMPOUND` |
 | `stopRotation` | `boolean?` | Lock rotation sync to render transform |
 
+`PhysicsPartParams` can be `RECTANGLE`, `CIRCLE`, `POLYGON`, `TRAPEZOID`, `FROM_VERTICES`, `CAPSULE`, `EDGE`, or `CHAIN`. Capsule / chain / concave vertex parts are flattened into the parent compound.
+
 Runtime fields:
 
 - `body: Matter.Body` — set by `PhysicsSystem` after the GameObject enters the scene.
@@ -41,6 +70,8 @@ Events on the `Physics` instance:
 - `'collisionActive'` — same signature
 - `'collisionEnd'` — same signature
 
+Compound / capsule / chain collisions arrive on the **parent** `Physics` (the engine walks `body.parent` so part hits still emit).
+
 ### `PhysicsSystemParams`
 
 | Field | Type | Notes |
@@ -48,7 +79,7 @@ Events on the `Physics` instance:
 | `world` | `DeepPartial<IWorldDefinition>` | **Required**. Must include `gravity: { x, y, scale }` (e.g. `{ x: 0, y: 1, scale: 0.001 }`) |
 | `resolution` | `number?` | **Must match `RendererSystem.resolution`** to keep bodies aligned with sprites |
 | `fps` | `number?` | Step rate |
-| `isTest` | `boolean?` | Adds a Pixi debug overlay drawn from Matter renderer |
+| `isTest` | `boolean?` | Adds a Pixi debug overlay drawn from Matter renderer (compound parts are outlined individually) |
 | `mouse` | `{ open, constraint? }?` | Optional Matter mouse constraint |
 | `element` / `canvas` | optional | Debug renderer mount points |
 
@@ -66,16 +97,21 @@ Events on the `Physics` instance:
   body's `position` / `rotation` back into the sibling `Transform`.
 - Pause / resume: `PhysicsSystem` automatically stops / starts the Matter
   runner when `Game.pause()` / `Game.resume()` is called.
+- Changing `bodyParams` (deep observer) rebuilds the Matter body.
 
 ## Common pitfalls
 
 | Symptom | Fix |
 |---------|-----|
-| `gravity` complaint at runtime | Provide `world: { gravity: { x: 0, y: 1, scale: 0.001 } }` (`scale` is required) |
+| `gravity` complaint at runtime | Provide `world: { gravity: { x, y, scale } }` (`scale` is required) |
 | Bodies misaligned with sprites | `PhysicsSystem.resolution` must match `RendererSystem.resolution` |
 | Rotation drift | Use `stopRotation: true` on `Physics` if the visual must stay axis-aligned |
 | Bodies pile up at origin | Set `position: { x, y }` on `Physics` constructor params |
 | Cannot tap through bodies | Disable mouse constraint or `pointer-events: none` on the canvas overlay |
+| `FROM_VERTICES` / `CHAIN` in the wrong place | Vertices are local to the body origin, not world space |
+| Nested `COMPOUND` throws | Flatten into one `parts` list, or use `CAPSULE` / `CHAIN` as a part |
+| Soft rope expected from `CHAIN` | `CHAIN` is a rigid polyline. Soft ropes need constraints, not this type |
+| Collision events missing on capsule / compound | Listen on the parent `Physics`; do not read `pair.bodyA.component` yourself |
 
 ## Minimal example
 
@@ -98,8 +134,47 @@ ball.addComponent(new Graphics(/* draw a circle */));
 ball.addComponent(new Physics({ type: PhysicsType.CIRCLE, radius: 25 }));
 ```
 
+### Extra shapes
+
+```ts
+new Physics({
+  type: PhysicsType.FROM_VERTICES,
+  vertices: [{ x: -40, y: 20 }, { x: 40, y: 20 }, { x: 0, y: -40 }],
+});
+
+new Physics({ type: PhysicsType.TRAPEZOID, width: 80, height: 40, slope: 0.4 });
+
+new Physics({ type: PhysicsType.CAPSULE, length: 80, radius: 16 });
+
+new Physics({
+  type: PhysicsType.COMPOUND,
+  parts: [
+    { type: PhysicsType.RECTANGLE, width: 80, height: 20 },
+    { type: PhysicsType.CIRCLE, radius: 16, position: { x: -40, y: 0 } },
+    { type: PhysicsType.CIRCLE, radius: 16, position: { x: 40, y: 0 } },
+  ],
+});
+
+new Physics({
+  type: PhysicsType.EDGE,
+  from: { x: -100, y: 0 },
+  to: { x: 100, y: 20 },
+  thickness: 4,
+  bodyOptions: { isStatic: true },
+});
+
+new Physics({
+  type: PhysicsType.CHAIN,
+  vertices: [{ x: -200, y: 0 }, { x: 0, y: 40 }, { x: 200, y: 0 }],
+  thickness: 4,
+  bodyOptions: { isStatic: true },
+});
+```
+
 ## Verification
 
 - `pnpm --filter @combos-fun/plugin-matterjs run build`
 - Run a 2D example with physics; bodies should fall under gravity, collide,
   and stay aligned with sprites.
+- For new hulls: a static `CHAIN` / `EDGE` should support falling circles;
+  a `CAPSULE` / `COMPOUND` should emit `collisionStart` on the parent `Physics`.

package/combos-plugin.json

@@ -4,7 +4,7 @@
   "category": "physics",
   "dimension": "2d",
   "isCore": false,
-  "keywords": ["matter-js", "2d", "physics", "collision", "rigid-body", "gravity"],
+  "keywords": ["matter-js", "2d", "physics", "collision", "rigid-body", "gravity", "capsule", "compound", "polygon"],
   "agentSkill": "./agent-skill.md",
   "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer"],
   "exports": ["PhysicsSystem", "Physics", "PhysicsType"]

package/dist/plugin-matterjs.cjs.js

@@ -3,17 +3,25 @@
 var tslib = require('tslib');
 var engine = require('@combos-fun/engine');
 var Matter = require('matter-js');
+var decomp = require('poly-decomp');
 var pixi_js = require('pixi.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var Matter__default = /*#__PURE__*/_interopDefault(Matter);
+var decomp__default = /*#__PURE__*/_interopDefault(decomp);
 
 exports.PhysicsType = void 0;
 (function (PhysicsType) {
     PhysicsType["RECTANGLE"] = "rectangle";
     PhysicsType["CIRCLE"] = "circle";
     PhysicsType["POLYGON"] = "polygon";
+    PhysicsType["TRAPEZOID"] = "trapezoid";
+    PhysicsType["FROM_VERTICES"] = "fromVertices";
+    PhysicsType["CAPSULE"] = "capsule";
+    PhysicsType["COMPOUND"] = "compound";
+    PhysicsType["EDGE"] = "edge";
+    PhysicsType["CHAIN"] = "chain";
 })(exports.PhysicsType || (exports.PhysicsType = {}));
 class Physics extends engine.Component {
     static { this.componentName = 'Physics'; }
@@ -36,41 +44,184 @@ class Physics extends engine.Component {
     }
 }
 
+const DEFAULT_THICKNESS = 4;
+const MIN_SEGMENT = 0.5;
+let decompRegistered = false;
+function ensureDecomp() {
+    if (decompRegistered) {
+        return;
+    }
+    const lib = decomp__default.default?.quickDecomp ? decomp__default.default : decomp__default.default?.default;
+    if (lib?.quickDecomp) {
+        Matter__default.default.Common.setDecomp(lib);
+    }
+    decompRegistered = true;
+}
 class BodiesFactory {
     constructor() {
         this.Bodies = Matter__default.default.Bodies;
+        ensureDecomp();
     }
     create(component) {
-        let body = null;
         const { gameObject, bodyParams } = component;
         const coordinate = this.getCoordinate(gameObject);
         const x = bodyParams.position ? bodyParams.position.x : coordinate.x;
         const y = bodyParams.position ? bodyParams.position.y : coordinate.y;
-        const halfW = (gameObject.transform.size.width * gameObject.transform.scale.x) / 2;
-        const halfH = (gameObject.transform.size.height * gameObject.transform.scale.y) / 2;
+        const transformWidth = gameObject.transform.size.width * gameObject.transform.scale.x;
+        const transformHeight = gameObject.transform.size.height * gameObject.transform.scale.y;
         /** Matter.circle approximates with a polygon; NaN/0 radius breaks vertices. */
-        const defaultRadius = Math.max(1, Math.min(halfW, halfH));
-        switch (bodyParams.type) {
+        const defaultRadius = Math.max(1, Math.min(transformWidth, transformHeight) / 2);
+        const body = this.createShape(bodyParams, {
+            x,
+            y,
+            transformWidth,
+            transformHeight,
+            defaultRadius,
+        }, false);
+        if (!body) {
+            throw new Error(`[plugin-matterjs] Failed to create body for type ${String(bodyParams.type)}`);
+        }
+        return body;
+    }
+    createShape(params, ctx, isPart) {
+        const options = params.bodyOptions;
+        switch (params.type) {
             case exports.PhysicsType.RECTANGLE: {
-                const width = gameObject.transform.size.width * gameObject.transform.scale.x;
-                const height = gameObject.transform.size.height * gameObject.transform.scale.y;
-                body = this.Bodies.rectangle(x, y, width, height, bodyParams.bodyOptions);
-                break;
+                const width = params.width ?? ctx.transformWidth;
+                const height = params.height ?? ctx.transformHeight;
+                return this.Bodies.rectangle(ctx.x, ctx.y, width, height, options);
             }
             case exports.PhysicsType.CIRCLE: {
-                const radius = bodyParams.radius ?? defaultRadius;
-                body = this.Bodies.circle(x, y, radius, bodyParams.bodyOptions);
-                break;
+                const radius = params.radius ?? ctx.defaultRadius;
+                return this.Bodies.circle(ctx.x, ctx.y, radius, options);
             }
             case exports.PhysicsType.POLYGON: {
-                const sides = Math.max(3, bodyParams.sides ?? 6);
-                const radius = bodyParams.radius ?? defaultRadius;
-                body = this.Bodies.polygon(x, y, sides, radius, bodyParams.bodyOptions);
-                break;
+                const sides = Math.max(3, params.sides ?? 6);
+                const radius = params.radius ?? ctx.defaultRadius;
+                return this.Bodies.polygon(ctx.x, ctx.y, sides, radius, options);
+            }
+            case exports.PhysicsType.TRAPEZOID: {
+                const width = params.width ?? ctx.transformWidth;
+                const height = params.height ?? ctx.transformHeight;
+                const slope = Math.min(Math.max(params.slope ?? 0.5, 0), 0.999);
+                return this.Bodies.trapezoid(ctx.x, ctx.y, width, height, slope, options);
             }
+            case exports.PhysicsType.FROM_VERTICES:
+                return this.createFromVertices(params, ctx, options);
+            case exports.PhysicsType.CAPSULE:
+                return this.createCapsule(params, ctx, options);
+            case exports.PhysicsType.EDGE:
+                return this.createEdge(params, ctx, options);
+            case exports.PhysicsType.CHAIN:
+                return this.createChain(params, ctx, options);
+            case exports.PhysicsType.COMPOUND:
+                if (isPart) {
+                    throw new Error('[plugin-matterjs] Nested COMPOUND parts are not supported');
+                }
+                return this.createCompound(params, ctx, options);
+            default:
+                throw new Error(`[plugin-matterjs] Unsupported PhysicsType: ${String(params.type)}`);
+        }
+    }
+    createFromVertices(params, ctx, options) {
+        const sets = params.vertexSets ?? (params.vertices ? [params.vertices] : []);
+        if (!sets.length || sets.some(set => !set || set.length < 3)) {
+            throw new Error('[plugin-matterjs] FROM_VERTICES requires vertices (or vertexSets) with at least 3 points each');
+        }
+        ensureDecomp();
+        const body = this.Bodies.fromVertices(ctx.x, ctx.y, sets, options, true);
+        if (!body) {
+            throw new Error('[plugin-matterjs] FROM_VERTICES produced an empty body');
         }
         return body;
     }
+    createCapsule(params, ctx, options) {
+        const radius = Math.max(1, params.radius ?? ctx.defaultRadius);
+        const length = Math.max(radius * 2, params.length ?? ctx.transformWidth);
+        const shaft = length - radius * 2;
+        if (shaft < MIN_SEGMENT) {
+            return this.Bodies.circle(ctx.x, ctx.y, radius, options);
+        }
+        const parts = [
+            this.Bodies.rectangle(ctx.x, ctx.y, shaft, radius * 2),
+            this.Bodies.circle(ctx.x - shaft / 2, ctx.y, radius),
+            this.Bodies.circle(ctx.x + shaft / 2, ctx.y, radius),
+        ];
+        return Matter__default.default.Body.create({ ...options, parts });
+    }
+    createEdge(params, ctx, options) {
+        if (!params.from || !params.to) {
+            throw new Error('[plugin-matterjs] EDGE requires from and to');
+        }
+        const x1 = ctx.x + params.from.x;
+        const y1 = ctx.y + params.from.y;
+        const x2 = ctx.x + params.to.x;
+        const y2 = ctx.y + params.to.y;
+        const dx = x2 - x1;
+        const dy = y2 - y1;
+        const len = Math.hypot(dx, dy);
+        if (len < MIN_SEGMENT) {
+            throw new Error('[plugin-matterjs] EDGE from/to are too close');
+        }
+        const thickness = Math.max(1, params.thickness ?? DEFAULT_THICKNESS);
+        const { angle: _ignored, ...rest } = options ?? {};
+        return this.Bodies.rectangle((x1 + x2) / 2, (y1 + y2) / 2, len, thickness, {
+            ...rest,
+            angle: Math.atan2(dy, dx),
+        });
+    }
+    createChain(params, ctx, options) {
+        const verts = params.vertices;
+        if (!verts || verts.length < 2) {
+            throw new Error('[plugin-matterjs] CHAIN requires vertices with at least 2 points');
+        }
+        const thickness = Math.max(1, params.thickness ?? DEFAULT_THICKNESS);
+        const parts = [];
+        for (let i = 0; i < verts.length - 1; i++) {
+            const a = verts[i];
+            const b = verts[i + 1];
+            const x1 = ctx.x + a.x;
+            const y1 = ctx.y + a.y;
+            const x2 = ctx.x + b.x;
+            const y2 = ctx.y + b.y;
+            const dx = x2 - x1;
+            const dy = y2 - y1;
+            const len = Math.hypot(dx, dy);
+            if (len < MIN_SEGMENT) {
+                continue;
+            }
+            parts.push(this.Bodies.rectangle((x1 + x2) / 2, (y1 + y2) / 2, len, thickness, { angle: Math.atan2(dy, dx) }));
+        }
+        if (!parts.length) {
+            throw new Error('[plugin-matterjs] CHAIN has no usable segments');
+        }
+        return Matter__default.default.Body.create({ ...options, parts });
+    }
+    createCompound(params, ctx, options) {
+        const partParams = params.parts;
+        if (!partParams?.length) {
+            throw new Error('[plugin-matterjs] COMPOUND requires a non-empty parts array');
+        }
+        const parts = [];
+        for (let i = 0; i < partParams.length; i++) {
+            const part = partParams[i];
+            const ox = ctx.x + (part.position?.x ?? 0);
+            const oy = ctx.y + (part.position?.y ?? 0);
+            const partBody = this.createShape(part, { ...ctx, x: ox, y: oy }, true);
+            parts.push(...this.asParts(partBody));
+        }
+        if (!parts.length) {
+            throw new Error('[plugin-matterjs] COMPOUND produced no parts');
+        }
+        return Matter__default.default.Body.create({ ...options, parts });
+    }
+    /** Unwrap a compound wrapper so it can be merged into another parent. */
+    asParts(body) {
+        if (body.parts && body.parts.length > 1) {
+            return body.parts.slice(1);
+        }
+        return [body];
+    }
     getCoordinate(gameObject) {
         const x = gameObject.transform.position.x + gameObject.transform.anchor.x * gameObject.parent.transform.size.width;
         const y = gameObject.transform.position.y + gameObject.transform.anchor.y * gameObject.parent.transform.size.height;
@@ -120,17 +271,20 @@ class MatterPixiDebugRenderer {
             if (body.render?.visible === false) {
                 continue;
             }
-            const verts = body.vertices;
-            if (!verts?.length) {
-                continue;
-            }
-            const v0 = verts[0];
-            g.moveTo(v0.x, v0.y);
-            for (let i = 1; i < verts.length; i++) {
-                g.lineTo(verts[i].x, verts[i].y);
+            const pieces = body.parts && body.parts.length > 1 ? body.parts.slice(1) : [body];
+            for (let p = 0; p < pieces.length; p++) {
+                const verts = pieces[p].vertices;
+                if (!verts?.length) {
+                    continue;
+                }
+                const v0 = verts[0];
+                g.moveTo(v0.x, v0.y);
+                for (let i = 1; i < verts.length; i++) {
+                    g.lineTo(verts[i].x, verts[i].y);
+                }
+                g.closePath();
+                g.stroke({ width: 1, color: 0x00e676, alpha: 0.9 });
             }
-            g.closePath();
-            g.stroke({ width: 1, color: 0x00e676, alpha: 0.9 });
         }
     }
     destroy() {
@@ -143,6 +297,21 @@ class MatterPixiDebugRenderer {
     }
 }
 
+/** Collision pairs often report a compound part, not the parent body. */
+function resolveLinkedComponent(body) {
+    let current = body;
+    while (current) {
+        const linked = current;
+        if (linked.component) {
+            return linked.component;
+        }
+        if (!current.parent || current.parent === current) {
+            break;
+        }
+        current = current.parent;
+    }
+    return undefined;
+}
 class PhysicsEngine {
     constructor(game, options) {
         this.debugRenderer = null;
@@ -216,19 +385,13 @@ class PhysicsEngine {
     add(component) {
         const body = this.createBodies(component);
         this.World.add(this.engine.world, [body]);
-        component.body = body;
-        component.Body = Matter__default.default.Body;
-        component.PhysicsEngine = this.engine;
-        component.Constraint = this.Constraint;
-        component.mouseConstraint = this.mouseConstraint;
-        component.World = this.World;
-        body.component = component;
+        this.linkComponent(component, body);
     }
     change(component) {
         const newBody = this.createBodies(component);
         this.World.remove(this.engine.world, component.body, true);
         this.World.add(this.engine.world, [newBody]);
-        component.body = newBody;
+        this.linkComponent(component, newBody);
     }
     remove(component) {
         this.World.remove(this.engine.world, component.body, true);
@@ -236,8 +399,20 @@ class PhysicsEngine {
     }
     createBodies(params) {
         const body = this.bodiesFactory.create(params);
+        if (!body) {
+            throw new Error('[plugin-matterjs] Failed to create Matter body');
+        }
         return body;
     }
+    linkComponent(component, body) {
+        component.body = body;
+        component.Body = Matter__default.default.Body;
+        component.PhysicsEngine = this.engine;
+        component.Constraint = this.Constraint;
+        component.mouseConstraint = this.mouseConstraint;
+        component.World = this.World;
+        body.component = component;
+    }
     initCollisionEvents() {
         this.collisionEvents.forEach(eventName => {
             Matter__default.default.Events.on(this.engine, eventName, (event) => {
@@ -245,8 +420,11 @@ class PhysicsEngine {
                 for (let i = 0; i < pairs.length; i++) {
                     const pair = pairs[i];
                     const { bodyA, bodyB } = pair;
-                    const componentA = bodyA.component;
-                    const componentB = bodyB.component;
+                    const componentA = resolveLinkedComponent(bodyA);
+                    const componentB = resolveLinkedComponent(bodyB);
+                    if (!componentA || !componentB) {
+                        continue;
+                    }
                     componentA.emit(eventName, componentB.gameObject, componentA.gameObject);
                     componentB.emit(eventName, componentA.gameObject, componentB.gameObject);
                 }
@@ -383,7 +561,7 @@ var PhysicsSystem = PhysicsSystem$1;
 /** Auto-generated by scripts/build-package.mjs — do not edit. */
 Object.assign(PhysicsSystem, {
     packageName: "@combos-fun/plugin-matterjs",
-    packageVersion: "0.0.42",
+    packageVersion: "0.0.44",
 });
 
 exports.Physics = Physics;