@combos-fun/plugin-cannon 0.0.42 → 0.0.44

package/README.md

@@ -2,7 +2,7 @@
 
 @combos-fun/plugin-cannon — part of the Combos Fun engine monorepo.
 
-Keywords: `cannon-es`, `3d`, `physics`, `collision`, `rigid-body`, `gravity`.
+Keywords: `cannon-es`, `3d`, `physics`, `collision`, `rigid-body`, `gravity`, `trimesh`, `compound`.
 
 ## Documentation
 

package/agent-skill.md

@@ -6,7 +6,7 @@ Pattern mirrors `plugin-matterjs` (2D): Component stores params, System observes
 
 ## When to read
 
-Read for any 3D physics task: gravity, collisions, rigid bodies, ground planes, cylinders / spheres, body-mesh sync.
+Read for any 3D physics task: gravity, collisions, rigid bodies, ground planes, cylinders / cones / capsules / tori, body-mesh sync, GLB colliders.
 
 ## Public API
 
@@ -15,7 +15,12 @@ import {
   Physics3DSystem,
   Physics3D,
   Physics3DType,
+  Physics3DConstraint,
+  Physics3DConstraintSystem,
   type Physics3DParams,
+  type Physics3DPartParams,
+  type Physics3DCollider,
+  type Physics3DConstraintParams,
   type Physics3DSystemParams,
 } from '@combos-fun/plugin-cannon';
 ```
@@ -24,29 +29,54 @@ import {
 
 | Value | Shape | Notes |
 |-------|-------|-------|
-| `BOX` | `CANNON.Box` | Half-extents from `width`/`height`/`depth` |
+| `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` |
+| `CYLINDER` | `CANNON.Cylinder` | `radiusTop`, `radiusBottom`, `height`, `segments` (Y axis) |
+| `CONE` | `CANNON.Cylinder(≈0, radius, height)` | Matches `Graphics3D` cone |
+| `PLANE` | `CANNON.Plane` or thin box | Infinite unless `finite: true` |
+| `TORUS` | Compound spheres | 8–12 spheres; tube = `tube` or `0.4 × radius` |
+| `CAPSULE` | Cylinder + 2 spheres | `height` is total height |
+| `COMPOUND` | `Body.addShape` list | From `parts` or sibling `Graphics3D.parts` |
+
+If `type` is omitted: use `parts` → `COMPOUND`, else sibling `Graphics3D.shape`, else `BOX`. Missing size fields fall back to the sibling `Graphics3D`.
+
+### `Physics3DCollider` (models)
+
+| Value | When | Notes |
+|-------|------|-------|
+| `manual` | default without `Model3D` | Use `type` / `parts` |
+| `aabb` | **default when a sibling `Model3D` exists and `type` / `parts` are omitted** | `Box3` after load, includes `scale*` |
+| `hull` | convex props | Convex hull of sampled vertices; holes fill in |
+| `trimesh` | static scenery only | Triangle mesh; `mass` is forced to `0` |
+
+Mesh colliders wait until `Model3D` has attached a `Group`. Changing `scale*` rebuilds the body. Skinned animation stays on the bind-pose mesh. Do not use `trimesh` on two dynamic models that must hit each other.
 
 ### `Physics3DParams`
 
 | Field | Type | Default | Notes |
 |-------|------|---------|-------|
-| `type` | `Physics3DType` | `BOX` | |
-| `mass` | `number` | `1` | `0` = static; `PLANE` always static |
+| `type` | `Physics3DType` | inferred | |
+| `mass` | `number` | `1` | `0` = static; infinite `PLANE` always 0; `trimesh` always 0 |
 | `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 |
+| `position` | `{x?, y?, z?}` | sibling pose or `0` | |
+| `rotation` | `{x?, y?, z?}` | sibling pose or `0` | Euler → quaternion |
+| `width`/`height`/`depth` | `number` | sibling or `1` | Box / finite plane |
+| `radius` | `number` | sibling or `0.5` | Sphere / cylinder / cone / torus / capsule |
+| `radiusTop`/`radiusBottom` | `number` | `radius` | Cylinder taper |
+| `segments` | `number` | `12` | |
+| `tube` | `number` | `0.4 × radius` | Torus tube |
+| `finite` | `boolean` | `false` | `PLANE` → thin box (`width` × `height` × 0.02) in XY |
+| `collider` | `Physics3DCollider` | see above | |
+| `parts` | `Physics3DPartParams[]` | sibling `Graphics3D.parts` | Local offsets; no nested `COMPOUND` |
 | `stopRotation` | `boolean` | `false` | Lock rotation sync |
 
+`PLANE` stays **infinite** unless `finite: true`. A 10×10 visual ground that should drop you at the edge is a thin `BOX` or `finite: true`. Infinite ground still needs `rotation: { x: -Math.PI/2 }`.
+
 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.
+`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), including `Transform3D`. So `Physics3D` + `Transform3D` / `Graphics3D` / `Model3D` on the same node stay in sync without custom glue code.
+
+If the visual is parented (`addChild`), Cannon stays in world space and `Physics3D` converts the body pose to **local** before writing siblings. A moving car with physics + visual-only wheels as children does not need physics on the wheels.
 
 `body: CANNON.Body` is injected by the engine after the body is created.
 
@@ -66,15 +96,33 @@ Listen on the `Physics3D` instance:
 
 ```ts
 physics3d.on('collisionStart', (otherGameObject, selfGameObject) => { ... });
+physics3d.on('collisionActive', (otherGameObject, selfGameObject) => { ... });
 physics3d.on('collisionEnd', (otherGameObject, selfGameObject) => { ... });
 ```
 
+`collisionActive` fires every `world.step` while the pair is still overlapping. Compound / torus / capsule hits still emit on this parent `Physics3D`.
+
+### `Physics3DConstraint`
+
+Put `Physics3DConstraint` on the same GameObject as `Physics3D`. `target` is the **other GameObject's `name`**. Both bodies must exist (pending until they do).
+
+| `type` | Cannon constraint |
+|--------|-------------------|
+| `hinge` | `HingeConstraint` (`pivotA*` / `pivotB*` / `axisA*` / `axisB*`, optional `motor` / `motorSpeed`) |
+| `point` | `PointToPointConstraint` |
+| `lock` | `LockConstraint` |
+| `distance` | `DistanceConstraint` (`distance`) |
+
+Add `Physics3DConstraintSystem` after `Physics3DSystem`.
+
 ## Required setup
 
 - Add `Renderer3DSystem` (from `plugin-renderer-3d`) **before**
   `Physics3DSystem`.
+- Add `Physics3DConstraintSystem` after `Physics3DSystem` when using joints.
 - Body creation is **lazy**: it happens only when `Physics3D` is added
   AND the `GameObject` has a parent (is in the scene hierarchy).
+- Mesh colliders are **lazier**: they wait for `Model3D` to finish loading.
 
 ## Runtime behaviour
 
@@ -88,9 +136,13 @@ physics3d.on('collisionEnd', (otherGameObject, selfGameObject) => { ... });
 
 | 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 |
+| Bodies fall forever | Infinite `PLANE` needs `rotation: { x: -Math.PI/2 }` and a sane Y |
+| Walk off a 10×10 visual plane and still stand | That plane is infinite; set `finite: true` or use a `BOX` |
+| Mesh not following body | `Physics3D` and the visual on the **same** `GameObject` |
+| GLB uses a 1×1×1 box | Default without `Model3D` is manual `BOX`. With `Model3D`, default is `aabb` after load |
+| Doorway blocked on a GLB house | `collider: 'trimesh'` and `mass: 0` (forced). `aabb` / `hull` fill holes |
+| Dynamic trimesh jitter | Don't; use `aabb` / `hull` for moving objects |
+| Body exists but no collision | `Physics3DSystem` after `Renderer3DSystem`; object is 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` |
 
@@ -107,6 +159,7 @@ const game = new Game({
     new Renderer3DSystem({ canvas, width: 750, height: 1334 }),
     new Graphics3DSystem(),
     new Physics3DSystem({ gravity: { x: 0, y: -9.82, z: 0 } }),
+    new Physics3DConstraintSystem(),
   ],
   onSystemsBootstrapComplete: (g) => {
     const scene = g.scene;
@@ -130,6 +183,16 @@ const game = new Game({
 });
 ```
 
+Model collider:
+
+```ts
+hero.addComponent(new Model3D({ resource: 'hero', positionY: 0 }));
+hero.addComponent(new Physics3D({ mass: 1 })); // aabb after the GLB loads
+
+building.addComponent(new Model3D({ resource: 'house' }));
+building.addComponent(new Physics3D({ collider: 'trimesh', mass: 0 }));
+```
+
 ## Verification
 
 - `pnpm --filter @combos-fun/plugin-cannon run build`

package/combos-plugin.json

@@ -4,8 +4,14 @@
   "category": "physics",
   "dimension": "3d",
   "isCore": false,
-  "keywords": ["cannon-es", "3d", "physics", "collision", "rigid-body", "gravity"],
+  "keywords": ["cannon-es", "3d", "physics", "collision", "rigid-body", "gravity", "trimesh", "compound", "constraint", "hinge"],
   "agentSkill": "./agent-skill.md",
   "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer-3d"],
-  "exports": ["Physics3DSystem", "Physics3D", "Physics3DType"]
+  "exports": [
+    "Physics3DSystem",
+    "Physics3D",
+    "Physics3DType",
+    "Physics3DConstraint",
+    "Physics3DConstraintSystem"
+  ]
 }