@combos-fun/plugin-cannon 0.0.6 → 0.0.7

package/README.md

@@ -1 +1,27 @@
 # @combos-fun/plugin-cannon
+
+@combos-fun/plugin-cannon — part of the Combos Fun engine monorepo.
+
+Keywords: `cannon-es`, `3d`, `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-cannon/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-cannon/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,145 @@
+# `@combos-fun/plugin-cannon` — Agent notes
+
+3D physics for Combos Fun. Wraps `cannon-es` ^0.20 and exposes a
+`Physics3DSystem` plus a `Physics3D` Component that auto-syncs
+`positionX/Y/Z` and `rotationX/Y/Z` to sibling 3D render components every
+frame.
+
+Pattern mirrors `plugin-matterjs` (2D): Component stores params, System
+observes + delegates to engine, engine manages `CANNON.World`.
+
+## When to read
+
+Read for any 3D physics task: gravity, collisions, rigid bodies, ground
+planes, cylinders / spheres, body-mesh sync.
+
+## Public API
+
+```ts
+import {
+  Physics3DSystem,
+  Physics3D,
+  Physics3DType,
+  type Physics3DParams,
+  type Physics3DSystemParams,
+} from '@combos-fun/plugin-cannon';
+```
+
+### `Physics3DType`
+
+| Value | Shape | Notes |
+|-------|-------|-------|
+| `BOX` | `CANNON.Box` | Half-extents from `width`/`height`/`depth` |
+| `SPHERE` | `CANNON.Sphere` | `radius` |
+| `CYLINDER` | `CANNON.Cylinder` | `radiusTop`, `radiusBottom`, `height`, `segments` |
+| `PLANE` | `CANNON.Plane` | Infinite ground; always `mass = 0` |
+
+### `Physics3DParams`
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `type` | `Physics3DType` | `BOX` | |
+| `mass` | `number` | `1` | `0` = static; `PLANE` always static |
+| `bodyOptions` | `object` | `{}` | `friction`, `restitution`, `linearDamping`, `angularDamping`, `fixedRotation` |
+| `position` | `{x?, y?, z?}` | `0,0,0` | |
+| `rotation` | `{x?, y?, z?}` | `0,0,0` | Euler → quaternion |
+| `width`/`height`/`depth` | `number` | `1` | Box dimensions |
+| `radius` | `number` | `0.5` | Sphere / cylinder radius |
+| `radiusTop`/`radiusBottom` | `number` | `radius` | Cylinder top/bottom |
+| `segments` | `number` | `16` | Cylinder radial segments |
+| `stopRotation` | `boolean` | `false` | Lock rotation sync |
+
+Synced public fields (read each `update`):
+
+`positionX`, `positionY`, `positionZ`, `rotationX`, `rotationY`,
+`rotationZ`. The system writes these back to **all sibling components**
+on the same `GameObject` that have those fields (duck-type check). So
+`Physics3D` + `Graphics3D` on the same node stay in sync without custom
+glue code.
+
+`body: CANNON.Body` is injected by the engine after the body is created.
+
+### `Physics3DSystemParams`
+
+| Field | Type | Default |
+|-------|------|---------|
+| `gravity` | `{x, y, z}` | `{ x: 0, y: -9.82, z: 0 }` |
+| `fixedTimeStep` | `number` | `1/60` |
+| `maxSubSteps` | `number` | `3` |
+| `allowSleep` | `boolean` | `false` |
+| `solver` | `{ iterations?, tolerance? }` | — |
+
+### Collision events
+
+Listen on the `Physics3D` instance:
+
+```ts
+physics3d.on('collisionStart', (otherGameObject, selfGameObject) => { ... });
+physics3d.on('collisionEnd', (otherGameObject, selfGameObject) => { ... });
+```
+
+## Required setup
+
+- Add `Renderer3DSystem` (from `plugin-renderer-3d`) **before**
+  `Physics3DSystem`.
+- Body creation is **lazy**: it happens only when `Physics3D` is added
+  AND the `GameObject` has a parent (is in the scene hierarchy).
+
+## Runtime behaviour
+
+- Each frame, `Physics3DSystem` steps the `CANNON.World` and writes back
+  position/rotation into the component.
+- The `update()` of `Physics3D` then propagates these fields to siblings
+  automatically.
+- `onDestroy` removes the body from `CANNON.World`.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| Bodies fall forever | `PLANE` rotated and mass 0 acts as ground; verify `rotation: { x: -Math.PI/2 }` and that it's at the right Y |
+| Mesh not following body | Make sure `Physics3D` and the visual (e.g. `Graphics3D`) are on the **same** `GameObject` |
+| Body exists but no collision | Check `Physics3DSystem` is registered after `Renderer3DSystem` and `GameObject` is actually in the scene hierarchy |
+| Continuous low-amplitude jitter on a stack | Increase `solver.iterations` or set `allowSleep: true` |
+| Want axis-aligned visual on rotating body | `stopRotation: true` |
+
+## Minimal example
+
+```ts
+import { Game, Scene, GameObject } from '@combos-fun/engine';
+import { Renderer3DSystem } from '@combos-fun/plugin-renderer-3d';
+import { Graphics3DSystem, Graphics3D } from '@combos-fun/plugin-renderer-3d-graphics';
+import { Physics3DSystem, Physics3D, Physics3DType } from '@combos-fun/plugin-cannon';
+
+const game = new Game({
+  systems: [
+    new Renderer3DSystem({ canvas, width: 750, height: 1000 }),
+    new Graphics3DSystem(),
+    new Physics3DSystem({ gravity: { x: 0, y: -9.82, z: 0 } }),
+  ],
+  onSystemsBootstrapComplete: (g) => {
+    const scene = g.getScene();
+
+    const box = new GameObject('box');
+    box.addComponent(new Graphics3D({ shape: 'box', width: 1, height: 1, depth: 1, color: 0xff0000 }));
+    box.addComponent(new Physics3D({
+      type: Physics3DType.BOX, mass: 1, width: 1, height: 1, depth: 1,
+      position: { x: 0, y: 5, z: 0 },
+    }));
+    scene.addChild(box);
+
+    const ground = new GameObject('ground');
+    ground.addComponent(new Graphics3D({ shape: 'plane', width: 10, height: 10, color: 0x888888 }));
+    ground.addComponent(new Physics3D({
+      type: Physics3DType.PLANE,
+      rotation: { x: -Math.PI / 2, y: 0, z: 0 },
+    }));
+    scene.addChild(ground);
+  },
+});
+```
+
+## Verification
+
+- `pnpm --filter @combos-fun/plugin-cannon run build`
+- Run a 3D physics example; box should fall and rest on the plane.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-cannon",
+  "pluginId": "cannon",
+  "category": "physics",
+  "dimension": "3d",
+  "isCore": false,
+  "keywords": ["cannon-es", "3d", "physics", "collision", "rigid-body", "gravity"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer-3d"],
+  "exports": ["Physics3DSystem", "Physics3D", "Physics3DType"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-cannon",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "@combos-fun/plugin-cannon",
   "main": "index.js",
   "module": "dist/plugin-cannon.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.cannon.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-cannon.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-cannon.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-cannon.d.ts",
   "keywords": [
     "combos-fun",
@@ -21,7 +35,7 @@
   "author": "sun668 <q947692259@gmail.com>",
   "dependencies": {
     "cannon-es": "^0.20.0",
-    "@combos-fun/engine": "0.0.6"
+    "@combos-fun/engine": "0.0.7"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"