@combos-fun/plugin-renderer-3d-graphics 0.1.15 → 0.1.17

package/agent-skill.md

@@ -1,73 +1,28 @@
 # `@combos-fun/plugin-renderer-3d-graphics` — Agent notes
 
-Procedural primitives and compound primitive groups. Use this for plain or texture-mapped boxes, spheres, cylinders, planes, cones, tori, and capsules.
-
-Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, named resources, pose seeding, hierarchy, and stale-async handling.
-
-## Public API
+Primitives and compound groups. Parent: `plugin-renderer-3d`.
 
 ```ts
-import {
-  Graphics3D,
-  Graphics3DSystem,
-  type Graphics3DParams,
-  type Graphics3DPartParams,
-  type Graphics3DMaterialKind,
-  type Graphics3DShape,
-} from '@combos-fun/plugin-renderer-3d-graphics';
+import { Graphics3D, Graphics3DSystem } from '@combos-fun/plugin-renderer-3d-graphics';
 ```
 
-`componentName = 'Graphics3D'`; `systemName = 'Graphics3DSystem'`.
-
-## Parameters
-
-| Field | Type | Default |
-|-------|------|---------|
-| `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` | `12` |
-| `tube` | `number` | `0`; torus resolves it to `0.4 × radius` |
-| `positionX/Y/Z` | `number` | `0` |
-| `rotationX/Y/Z` | `number` | `0` radians |
-| `scaleX/Y/Z` | `number` | `1` |
-| `opacity` | `number` | `1` |
-| `roughness` / `metalness` | `number` | `1` / `0` |
-| `emissive` | `number` | `0` |
-| `map` | `string` | `''` (`IMAGE` resource name) |
-| `doubleSide` | `boolean` | `false` |
-| `material` | `'standard' \| 'basic' \| 'lambert' \| 'toon'` | `'standard'` |
-| `parts` | `Graphics3DPartParams[]` | `undefined` |
-
-When non-empty, `parts` replaces the single primitive. Each part inherits component values and may override geometry, appearance, and its local pose; the component pose moves the resulting `Group`.
-
-Geometry mapping is direct to Three.js. Plane segments apply to both axes; capsule `height` is total height. Geometry and materials are reference-counted caches. Creating or rebuilding a mapped primitive is async; stale preparation releases acquired cache entries instead of attaching them.
-
-Non-pose changes rebuild the group. Pose changes are synchronized per frame without rebuilding. A sibling `Material3D` can replace the generated materials.
-
-## Package-specific pitfalls
-
-- A plane is single-sided unless `doubleSide: true`.
-- A visual `PlaneGeometry` is finite; Cannon `Physics3DType.PLANE` is infinite unless `finite: true`.
-- Lit materials may look dark without enough light; `basic` is unlit.
-- Unknown ctor fields (`type`, `geometry`, a Three `material: { color }` bag, `as never`) are ignored and warned. They used to be `Object.assign`'d onto the component — a material object overwrites the shader string and the mesh vanishes. Use `shape` + sibling `color` / `roughness` / `metalness`.
-- Prefer `parts` for one compound visual. Use child GameObjects when parts need independent components or physics.
-- Physics and graphics should share a GameObject when physics owns its pose.
-
-## Minimal example
-
-```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 },
-  ],
-}));
-```
-
-## Verification
-
-`pnpm --filter @combos-fun/plugin-renderer-3d-graphics run build`
+`componentName = 'Graphics3D'`. `systemName = 'Graphics3DSystem'`.
+
+| Field | Default |
+| --- | --- |
+| `shape` | `'box'` — `box \| sphere \| cylinder \| plane \| cone \| torus \| capsule` |
+| `color` | `0x00ff00` |
+| `material` | `'standard'` — `standard \| basic \| lambert \| toon` |
+| `width` / `height` / `depth` | `1` |
+| `radius` | `0.5` |
+| `segments` | `12` |
+| `tube` | `0` (torus uses `0.4 × radius`) |
+| `roughness` / `metalness` | `1` / `0` |
+| `emissive` | `0` |
+| `opacity` | `1` |
+| `map` | `''` — IMAGE resource name |
+| `wireframe` / `doubleSide` | `false` |
+| `position*` / `rotation*` / `scale*` | `0` / `0` / `1` |
+| `parts` | replaces the single primitive; component pose moves the group |
+
+`color`, `roughness`, `metalness`, and `emissive` are siblings of `material`. `type`, `geometry`, and a material object are ignored. Planes are single-sided unless `doubleSide: true`. A visual plane is finite; Cannon `PLANE` is not. `basic` is unlit; lit materials stay dark without light. Capsule `height` is total height. Plane `segments` apply to both axes. Each part inherits the component and can override geometry, look, and local pose. Use child GameObjects when parts need their own components or physics. Non-pose changes rebuild the mesh. Mapped textures load async and drop stale results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-graphics",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Procedural 3D primitive shapes",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-graphics.esm.js",
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "three": "^0.172.0",
-    "@combos-fun/engine": "0.1.15",
-    "@combos-fun/inspector-decorator": "0.1.15",
-    "@combos-fun/plugin-renderer-3d": "0.1.15"
+    "@combos-fun/engine": "0.1.17",
+    "@combos-fun/plugin-renderer-3d": "0.1.17",
+    "@combos-fun/inspector-decorator": "0.1.17"
   },
   "keywords": [
     "combos-fun",