@combos-fun/plugin-renderer-3d-graphics 0.0.42 → 0.0.45

package/README.md

@@ -2,7 +2,7 @@
 
 @combos-fun/plugin-renderer-3d-graphics — part of the Combos Fun engine monorepo.
 
-Keywords: `3d`, `graphics`, `primitives`, `box`, `sphere`, `cylinder`, `plane`.
+Keywords: `3d`, `graphics`, `primitives`, `box`, `sphere`, `cylinder`, `plane`, `cone`, `torus`, `capsule`.
 
 ## Documentation
 

package/agent-skill.md

@@ -1,17 +1,17 @@
 # `@combos-fun/plugin-renderer-3d-graphics` — Agent notes
 
-Procedural 3D primitive shapes for the 3D pipeline. Produces a `THREE.Mesh` with a `MeshStandardMaterial` based on the chosen `shape`.
+Procedural 3D primitives for the 3D pipeline. One `Graphics3D` becomes either a shared `InstancedMesh` (identical singles) or a `Group` of meshes (`parts`).
 
 ## When to read
 
-Read for any procedural primitive: box, sphere, cylinder, plane, cone, torus, debug placeholders, simple terrain.
+Read for any procedural primitive: box, sphere, cylinder, plane, cone, torus, capsule, debug placeholders, simple terrain, compound furniture.
 
 Read **before** guessing that 3D has no rotation or no per-frame pose — do not wait for a compile error. Pose fields and a chase-camera pattern are below.
 
 ## Public API
 
 ```ts
-import { Graphics3D, Graphics3DSystem, type Graphics3DParams } from '@combos-fun/plugin-renderer-3d-graphics';
+import { Graphics3D, Graphics3DSystem, type Graphics3DParams, type Graphics3DPartParams } from '@combos-fun/plugin-renderer-3d-graphics';
 ```
 
 `componentName = 'Graphics3D'`, `systemName = 'Graphics3DSystem'`.
@@ -20,31 +20,46 @@ import { Graphics3D, Graphics3DSystem, type Graphics3DParams } from '@combos-fun
 
 | Field | Type | Default |
 |-------|------|---------|
-| `shape` | `'box' \| 'sphere' \| 'cylinder' \| 'plane' \| 'cone' \| 'torus'` | `'box'` |
+| `shape` | `'box' \| 'sphere' \| 'cylinder' \| 'plane' \| 'cone' \| 'torus' \| 'capsule'` | `'box'` |
 | `color` | `number` | `0x00ff00` |
 | `wireframe` | `boolean` | `false` |
 | `width` / `height` / `depth` | `number` | `1` |
 | `radius` | `number` | `0.5` |
-| `segments` | `number` | `32` |
+| `segments` | `number` | `12` |
+| `tube` | `number` | `0` → `0.4 × radius` (torus only) |
 | `positionX` / `Y` / `Z` | `number` | `0` |
 | `rotationX` / `Y` / `Z` | `number` | `0` |
 | `scaleX` / `Y` / `Z` | `number` | `1` |
 | `opacity` | `number` | `1` |
+| `roughness` / `metalness` | `number` | `1` / `0` (`standard` only) |
+| `emissive` | `number` | `0` (hex) |
+| `map` | `string` | `''` (engine `IMAGE` name) |
+| `doubleSide` | `boolean` | `false` |
+| `material` | `'standard' \| 'basic' \| 'lambert' \| 'toon'` | `'standard'` |
+| `instanced` | `boolean` | `true` |
+| `parts` | `Graphics3DPartParams[]` | — |
 
-Shape → Three.js geometry: `box → BoxGeometry`, `sphere → SphereGeometry`, `cylinder → CylinderGeometry`, `plane → PlaneGeometry`, `cone → ConeGeometry`, `torus → TorusGeometry`.
+`parts` replaces the single primitive. Each part can override shape / color / map / local pose. The component pose still moves the whole group.
+
+Shape → Three.js geometry: `box → BoxGeometry`, `sphere → SphereGeometry`, `cylinder → CylinderGeometry`, `plane → PlaneGeometry` (uses `segments` as width/height segs), `cone → ConeGeometry`, `torus → TorusGeometry`, `capsule → CapsuleGeometry` (`height` is total height).
+
+Identical singles (same geometry + material, `instanced !== false`, no `parts`) share one `InstancedMesh`. Geometry and materials are cached.
 
 ## Required setup
 
-`Renderer3DSystem` then `Graphics3DSystem`.
+`Renderer3DSystem` then `Graphics3DSystem`. For `map`, register `RESOURCE_TYPE.IMAGE` first. Pose can live on sibling `Transform3D` (preferred once a hierarchy exists); `Graphics3D.position*` still seeds / updates it.
 
 ## Common pitfalls
 
 | Symptom | Fix |
 |---------|-----|
-| Plane invisible from one side | There is no `doubleSide` field. Rotate the plane so the camera sees the front |
-| Sphere very dark | Increase scene light or use `MeshBasicMaterial`-style flat shading (not exposed; use `Img3D` if you need flat) |
+| Plane invisible from one side | Set `doubleSide: true`, or rotate so the camera sees the front |
+| Sphere very dark | Raise lights / `Renderer3DSystem` hemisphere, or use `material: 'basic'` |
 | Wireframe shimmer | `wireframe: true` — that's by design |
-| Sync drift with `Physics3D` | Make sure both are on the same `GameObject`; `Physics3D.update()` writes positions back automatically |
+| Sync drift with `Physics3D` | Same `GameObject`; `Physics3D.update()` writes positions back |
+| `map` throws `Unknown resource` | Use the engine resource name, not a URL |
+| Compound house as 3 GameObjects | Prefer one `Graphics3D` with `parts`, or `parent.addChild(child)` so the child mesh hangs off the parent |
+| Child does not follow parent | `car.addChild(wheel)` — child `position*` are local. Do not also write world-space pose onto the wheel each frame unless it has its own `Physics3D` |
 
 ## Minimal example
 
@@ -54,10 +69,27 @@ box.addComponent(new Graphics3D({
   shape: 'box',
   width: 1, height: 1, depth: 1,
   color: 0xff0000,
+  roughness: 0.8,
   positionX: 0, positionY: 1, positionZ: 0,
 }));
 ```
 
+```ts
+const house = new GameObject('house');
+house.addComponent(new Graphics3D({
+  parts: [
+    { shape: 'box', width: 2, height: 1.2, depth: 2, color: 0xc4a574 },
+    { shape: 'cone', radius: 1.4, height: 1, color: 0x8b2942, positionY: 1.1 },
+  ],
+}));
+
+const car = new GameObject('car');
+car.addComponent(new Graphics3D({ shape: 'box', width: 2, height: 0.6, depth: 1, color: 0x3366ff }));
+const wheel = new GameObject('wheel');
+wheel.addComponent(new Graphics3D({ shape: 'cylinder', radius: 0.3, height: 0.2, color: 0x222222, rotationZ: Math.PI / 2, positionX: 0.7, positionY: -0.2 }));
+car.addChild(wheel);
+```
+
 ## Per-frame pose + chase camera
 
 `rotationX/Y/Z` and `positionX/Y/Z` are writable every tick. Use `Component.update` (`deltaTime` is milliseconds). Camera: `this.game.getSystem(Renderer3DSystem).threeContext.camera`. Do not hide `#canvas` or draw a second Canvas 2D game.
@@ -67,7 +99,7 @@ box.addComponent(new Graphics3D({
 | Static placemarker cube → “no rotation / don’t know how to change pose each frame” | Assign `graphics.rotationY` / `positionX` / `positionZ` in `update` |
 | Hide WebGL `#canvas` and cover the viewport with Canvas 2D / DOM fake perspective | Keep `#canvas` visible and interactive; keep drawing with `Graphics3D` / `Model3D` |
 | `setInterval` / extra `requestAnimationFrame` to move the mesh | `Component.update` so pause/resume follows `Game.ticker` |
-| 2D `TransformParams` on a 3D GameObject | Pose lives on `Graphics3D` (or `Model3D` / `Img3D`) fields |
+| 2D `TransformParams` on a 3D GameObject | Pose lives on `Transform3D` (or `Graphics3D` / `Model3D` / `Img3D` fields, which seed `Transform3D`) |
 
 ```ts
 class ChaseCraft extends Component {

package/combos-plugin.json

@@ -4,7 +4,7 @@
   "category": "rendering",
   "dimension": "3d",
   "isCore": false,
-  "keywords": ["3d", "graphics", "primitives", "box", "sphere", "cylinder", "plane"],
+  "keywords": ["3d", "graphics", "primitives", "box", "sphere", "cylinder", "plane", "cone", "torus", "capsule"],
   "agentSkill": "./agent-skill.md",
   "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer-3d"],
   "exports": ["Graphics3D", "Graphics3DSystem"]