@combos-fun/plugin-matterjs 0.0.6 → 0.0.8

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/plugin-matterjs
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/plugin-matterjs — part of the Combos Fun engine monorepo.
+
+Keywords: `matter-js`, `2d`, `physics`, `collision`, `rigid-body`, `gravity`.
+
+## Documentation
+
+- Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)
+- Machine-readable manifest: [`combos-plugin.json`](./combos-plugin.json)
+  (validated against `schemas/combos-plugin.schema.json` in the repo
+  root)
+- Entry skill (single source of truth for AI agents working with this
+  monorepo): `skills/combos-engine-development/SKILL.md`
+
+When consumed from npm, the manifest and agent notes are exposed as
+stable subpaths:
+
+```ts
+import manifest from '@combos-fun/plugin-matterjs/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-matterjs/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,106 @@
+# `@combos-fun/plugin-matterjs` — Agent notes
+
+2D physics for Combos Fun. Wraps `matter-js` ^0.20 and exposes a `PhysicsSystem` plus a `Physics` Component that auto-syncs body position / rotation to a sibling display object's `Transform` each frame.
+
+## When to read
+
+Read for any 2D physics task: gravity, collisions, kinematic / static bodies, mouse constraints, rigid-body alignment with sprites.
+
+## Public API
+
+```ts
+import {
+  PhysicsSystem,
+  Physics,
+  PhysicsType,
+  type PhysicsSystemParams,
+} from '@combos-fun/plugin-matterjs';
+```
+
+### `PhysicsType`
+
+`RECTANGLE`, `CIRCLE`, `POLYGON`.
+
+### `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 |
+| `stopRotation` | `boolean?` | Lock rotation sync to render transform |
+
+Runtime fields:
+
+- `body: Matter.Body` — set by `PhysicsSystem` after the GameObject enters the scene.
+
+Events on the `Physics` instance:
+
+- `'collisionStart'` — `(otherGameObject, selfGameObject) => void`
+- `'collisionActive'` — same signature
+- `'collisionEnd'` — same signature
+
+### `PhysicsSystemParams`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `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 |
+| `mouse` | `{ open, constraint? }?` | Optional Matter mouse constraint |
+| `element` / `canvas` | optional | Debug renderer mount points |
+
+## Required setup
+
+- Add `RendererSystem` (from `plugin-renderer`) **before** `PhysicsSystem`.
+- Match `resolution` between renderer and physics.
+- Use `Transform.origin: { x: 0.5, y: 0.5 }` so the body's center aligns
+  with the sprite center.
+- Bodies are created lazily when the `GameObject` is added to a scene.
+
+## Runtime behaviour
+
+- Each frame, `PhysicsSystem` steps the Matter `Engine` and then writes the
+  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.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| `gravity` complaint at runtime | Provide `world: { gravity: { x: 0, y: 1, scale: 0.001 } }` (`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 |
+
+## Minimal example
+
+```ts
+import { Game, GameObject, Transform } from '@combos-fun/engine';
+import { RendererSystem } from '@combos-fun/plugin-renderer';
+import { GraphicsSystem, Graphics } from '@combos-fun/plugin-renderer-graphics';
+import { PhysicsSystem, Physics, PhysicsType } from '@combos-fun/plugin-matterjs';
+
+const game = new Game({
+  systems: [
+    new RendererSystem({ canvas, width: 750, height: 1334 }),
+    new GraphicsSystem(),
+    new PhysicsSystem({ world: { gravity: { x: 0, y: 1, scale: 0.001 } } }),
+  ],
+});
+
+const ball = new GameObject('ball');
+ball.addComponent(new Transform({ position: { x: 375, y: 100 }, origin: { x: 0.5, y: 0.5 } }));
+ball.addComponent(new Graphics(/* draw a circle */));
+ball.addComponent(new Physics({ type: PhysicsType.CIRCLE, radius: 25 }));
+```
+
+## 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.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-matterjs",
+  "pluginId": "matterjs",
+  "category": "physics",
+  "dimension": "2d",
+  "isCore": false,
+  "keywords": ["matter-js", "2d", "physics", "collision", "rigid-body", "gravity"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer"],
+  "exports": ["PhysicsSystem", "Physics", "PhysicsType"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-matterjs",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "@combos-fun/plugin-matterjs",
   "main": "index.js",
   "module": "dist/plugin-matterjs.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.renderer.matterjs.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-matterjs.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-matterjs.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-matterjs.d.ts",
   "keywords": [
     "combos-fun",
@@ -21,7 +35,7 @@
     "matter-js": "^0.20.0",
     "pixi.js": "^8.18.1",
     "poly-decomp": "^0.3.0",
-    "@combos-fun/engine": "0.0.6"
+    "@combos-fun/engine": "0.0.8"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"