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

package/agent-skill.md

@@ -1,22 +1,25 @@
 # `@combos-fun/plugin-renderer-3d-graphics` — Agent notes
 
-Procedural 3D primitives for the 3D pipeline. One `Graphics3D` becomes either a shared `InstancedMesh` (identical singles) or a `Group` of meshes (`parts`).
+Procedural primitives and compound primitive groups. Use this for plain or texture-mapped boxes, spheres, cylinders, planes, cones, tori, and capsules.
 
-## When to read
-
-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.
+Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, named resources, pose seeding, hierarchy, and stale-async handling.
 
 ## Public API
 
 ```ts
-import { Graphics3D, Graphics3DSystem, type Graphics3DParams, type Graphics3DPartParams } from '@combos-fun/plugin-renderer-3d-graphics';
+import {
+  Graphics3D,
+  Graphics3DSystem,
+  type Graphics3DParams,
+  type Graphics3DPartParams,
+  type Graphics3DMaterialKind,
+  type Graphics3DShape,
+} from '@combos-fun/plugin-renderer-3d-graphics';
 ```
 
-`componentName = 'Graphics3D'`, `systemName = 'Graphics3DSystem'`.
+`componentName = 'Graphics3D'`; `systemName = 'Graphics3DSystem'`.
 
-### `Graphics3DParams`
+## Parameters
 
 | Field | Type | Default |
 |-------|------|---------|
@@ -26,54 +29,34 @@ import { Graphics3D, Graphics3DSystem, type Graphics3DParams, type Graphics3DPar
 | `width` / `height` / `depth` | `number` | `1` |
 | `radius` | `number` | `0.5` |
 | `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` |
+| `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` (`standard` only) |
-| `emissive` | `number` | `0` (hex) |
-| `map` | `string` | `''` (engine `IMAGE` name) |
+| `roughness` / `metalness` | `number` | `1` / `0` |
+| `emissive` | `number` | `0` |
+| `map` | `string` | `''` (`IMAGE` resource name) |
 | `doubleSide` | `boolean` | `false` |
 | `material` | `'standard' \| 'basic' \| 'lambert' \| 'toon'` | `'standard'` |
-| `instanced` | `boolean` | `true` |
-| `parts` | `Graphics3DPartParams[]` | — |
-
-`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).
+| `parts` | `Graphics3DPartParams[]` | `undefined` |
 
-Identical singles (same geometry + material, `instanced !== false`, no `parts`) share one `InstancedMesh`. Geometry and materials are cached.
+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`.
 
-## Required setup
+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.
 
-`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.
+Non-pose changes rebuild the group. Pose changes are synchronized per frame without rebuilding. A sibling `Material3D` can replace the generated materials.
 
-## Common pitfalls
+## Package-specific pitfalls
 
-| Symptom | Fix |
-|---------|-----|
-| 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` | 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` |
+- 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.
+- 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 box = new GameObject('box');
-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({
@@ -82,47 +65,8 @@ house.addComponent(new Graphics3D({
     { 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.
-
-| Wrong | Correct |
-|-------|---------|
-| 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 `Transform3D` (or `Graphics3D` / `Model3D` / `Img3D` fields, which seed `Transform3D`) |
-
-```ts
-class ChaseCraft extends Component {
-  static componentName = 'ChaseCraft';
-  heading = 0;
-  update(frame: UpdateParams) {
-    const mesh = this.gameObject.getComponent(Graphics3D);
-    const camera = this.game.getSystem(Renderer3DSystem).threeContext.camera;
-    const dt = frame.deltaTime / 1000;
-    this.heading += dt * 0.4;
-    mesh.rotationY = this.heading;
-    mesh.positionX += Math.sin(this.heading) * 6 * dt;
-    mesh.positionZ += Math.cos(this.heading) * 6 * dt;
-    camera.position.set(
-      mesh.positionX - Math.sin(this.heading) * 8,
-      mesh.positionY + 3,
-      mesh.positionZ - Math.cos(this.heading) * 8,
-    );
-    camera.lookAt(mesh.positionX, mesh.positionY, mesh.positionZ);
-  }
-}
 ```
 
 ## Verification
 
-`pnpm --filter @combos-fun/plugin-renderer-3d-graphics run build`.
+`pnpm --filter @combos-fun/plugin-renderer-3d-graphics run build`

package/dist/plugin-renderer-3d-graphics.cjs.js

@@ -34,7 +34,7 @@ class Graphics3D extends engine.Component {
         this.map = '';
         this.doubleSide = false;
         this.material = 'standard';
-        this.instanced = true;
+        this.parts = undefined;
     }
     static { this.componentName = 'Graphics3D'; }
     init(obj) {
@@ -293,140 +293,6 @@ tslib.__decorate([
         enumOptions: ['standard', 'basic', 'lambert', 'toon'],
     })
 ], Graphics3D.prototype, "material", void 0);
-tslib.__decorate([
-    inspectorDecorator.Field({
-        type: 'boolean',
-        group: 'Graphics3D',
-        label: 'instanced',
-        description: 'Share an InstancedMesh with identical primitives.',
-        editor: 'toggle',
-    })
-], Graphics3D.prototype, "instanced", void 0);
-
-const _pos = new three.Vector3();
-const _quat = new three.Quaternion();
-const _scale = new three.Vector3();
-const _euler = new three.Euler();
-const _mat = new three.Matrix4();
-const _swap = new three.Matrix4();
-function composePose(px, py, pz, rx, ry, rz, sx, sy, sz, target = _mat) {
-    _pos.set(px, py, pz);
-    _euler.set(rx, ry, rz);
-    _quat.setFromEuler(_euler);
-    _scale.set(sx, sy, sz);
-    return target.compose(_pos, _quat, _scale);
-}
-class InstanceBuckets {
-    constructor(scene, shadows) {
-        this.scene = scene;
-        this.shadows = shadows;
-        this.buckets = new Map();
-    }
-    add(key, id, geometry, material, matrix) {
-        let bucket = this.buckets.get(key);
-        if (!bucket) {
-            bucket = this.create(key, geometry, material);
-        }
-        if (bucket.live >= bucket.capacity) {
-            this.grow(bucket);
-        }
-        const index = bucket.live;
-        bucket.ids[index] = id;
-        bucket.indexOf.set(id, index);
-        bucket.mesh.setMatrixAt(index, matrix);
-        bucket.live += 1;
-        bucket.mesh.count = bucket.live;
-        bucket.mesh.instanceMatrix.needsUpdate = true;
-    }
-    setMatrix(key, id, matrix) {
-        const bucket = this.buckets.get(key);
-        if (!bucket)
-            return;
-        const index = bucket.indexOf.get(id);
-        if (index == null)
-            return;
-        bucket.mesh.setMatrixAt(index, matrix);
-        bucket.mesh.instanceMatrix.needsUpdate = true;
-    }
-    remove(key, id) {
-        const bucket = this.buckets.get(key);
-        if (!bucket)
-            return;
-        const index = bucket.indexOf.get(id);
-        if (index == null)
-            return;
-        const last = bucket.live - 1;
-        if (index !== last) {
-            const lastId = bucket.ids[last];
-            bucket.mesh.getMatrixAt(last, _swap);
-            bucket.mesh.setMatrixAt(index, _swap);
-            bucket.ids[index] = lastId;
-            if (typeof lastId === 'number') {
-                bucket.indexOf.set(lastId, index);
-            }
-        }
-        bucket.ids[last] = undefined;
-        bucket.indexOf.delete(id);
-        bucket.live -= 1;
-        bucket.mesh.count = bucket.live;
-        bucket.mesh.instanceMatrix.needsUpdate = true;
-        if (bucket.live <= 0) {
-            this.scene.remove(bucket.mesh);
-            bucket.mesh.dispose();
-            this.buckets.delete(key);
-        }
-    }
-    clear() {
-        for (const bucket of this.buckets.values()) {
-            this.scene.remove(bucket.mesh);
-            bucket.mesh.dispose();
-        }
-        this.buckets.clear();
-    }
-    create(key, geometry, material) {
-        const capacity = 8;
-        const mesh = new three.InstancedMesh(geometry, material, capacity);
-        mesh.count = 0;
-        mesh.frustumCulled = false;
-        mesh.castShadow = this.shadows;
-        mesh.receiveShadow = this.shadows;
-        const ids = new Array(capacity);
-        mesh.userData[pluginRenderer3d.COMBOS_INSTANCE_GAME_OBJECT_IDS] = ids;
-        this.scene.add(mesh);
-        const bucket = {
-            mesh,
-            ids,
-            indexOf: new Map(),
-            live: 0,
-            capacity,
-            geometry,
-            material,
-        };
-        this.buckets.set(key, bucket);
-        return bucket;
-    }
-    grow(bucket) {
-        const capacity = bucket.capacity * 2;
-        const mesh = new three.InstancedMesh(bucket.geometry, bucket.material, capacity);
-        mesh.count = bucket.live;
-        mesh.frustumCulled = false;
-        mesh.castShadow = this.shadows;
-        mesh.receiveShadow = this.shadows;
-        const ids = new Array(capacity);
-        for (let i = 0; i < bucket.live; i++) {
-            bucket.mesh.getMatrixAt(i, _swap);
-            mesh.setMatrixAt(i, _swap);
-            ids[i] = bucket.ids[i];
-        }
-        mesh.userData[pluginRenderer3d.COMBOS_INSTANCE_GAME_OBJECT_IDS] = ids;
-        this.scene.remove(bucket.mesh);
-        bucket.mesh.dispose();
-        this.scene.add(mesh);
-        bucket.mesh = mesh;
-        bucket.ids = ids;
-        bucket.capacity = capacity;
-    }
-}
 
 function torusTube(radius, tube) {
     return tube && tube > 0 ? tube : radius * 0.4;
@@ -697,17 +563,15 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
         this.entries = new Map();
         this.geos = new GeometryCache();
         this.mats = new MaterialCache();
-        this.buckets = null;
     }
     static { this.systemName = 'Graphics3DSystem'; }
     init() {
         const renderer3DSystem = this.game.getSystem(pluginRenderer3d.Renderer3DSystem);
         renderer3DSystem.rendererManager.register(this);
-        this.buckets = new InstanceBuckets(this.threeContext.scene, !!this.threeContext.shadows);
     }
     componentChanged(changed) {
         if (changed.componentName === 'Transform') {
-            this.handleHierarchyChange(changed.gameObject);
+            this.threeContext.reparentGameObject(changed.gameObject);
             return;
         }
         if (changed.componentName !== 'Graphics3D')
@@ -738,25 +602,17 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
         const next = poseKey(component.positionX, component.positionY, component.positionZ, component.rotationX, component.rotationY, component.rotationZ, component.scaleX, component.scaleY, component.scaleZ);
         if (!applyVisualPose) {
             entry.lastPose = next;
-            if (entry.group) {
-                entry.group.position.set(0, 0, 0);
-                entry.group.rotation.set(0, 0, 0);
-                entry.group.scale.set(1, 1, 1);
-            }
+            entry.group.position.set(0, 0, 0);
+            entry.group.rotation.set(0, 0, 0);
+            entry.group.scale.set(1, 1, 1);
             return;
         }
         if (entry.lastPose === next)
             return;
         entry.lastPose = next;
-        if (entry.mode === 'instance' && entry.bucketKey) {
-            this.buckets?.setMatrix(entry.bucketKey, gameObject.id, composePose(component.positionX, component.positionY, component.positionZ, component.rotationX, component.rotationY, component.rotationZ, component.scaleX, component.scaleY, component.scaleZ));
-            return;
-        }
-        if (entry.group) {
-            entry.group.position.set(component.positionX, component.positionY, component.positionZ);
-            entry.group.rotation.set(component.rotationX, component.rotationY, component.rotationZ);
-            entry.group.scale.set(component.scaleX, component.scaleY, component.scaleZ);
-        }
+        entry.group.position.set(component.positionX, component.positionY, component.positionZ);
+        entry.group.rotation.set(component.rotationX, component.rotationY, component.rotationZ);
+        entry.group.scale.set(component.scaleX, component.scaleY, component.scaleZ);
     }
     async mount(gameObject, component) {
         const asyncId = this.increaseAsyncId(gameObject.id);
@@ -772,7 +628,7 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
             this.releasePrepared(prepared);
             return;
         }
-        this.attach(gameObject, component, prepared);
+        this.attachGroup(gameObject, component, prepared);
     }
     async prepare(component) {
         const specs = this.resolveParts(component);
@@ -802,50 +658,7 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
         }
         return [resolvePrimitive(component)];
     }
-    handleHierarchyChange(gameObject) {
-        const parent = gameObject.parent;
-        if (parent && parent !== gameObject.scene) {
-            this.ensureGroupMode(parent);
-        }
-        this.ensureGroupMode(gameObject);
-        this.threeContext.reparentGameObject(gameObject);
-    }
-    ensureGroupMode(gameObject) {
-        const entry = this.entries.get(gameObject.id);
-        if (!entry || entry.mode !== 'instance')
-            return;
-        const component = gameObject.getComponent(Graphics3D);
-        if (!component)
-            return;
-        if (entry.bucketKey) {
-            this.buckets?.remove(entry.bucketKey, gameObject.id);
-        }
-        this.attachGroup(gameObject, component, entry.prepared, entry.lastPose);
-    }
-    attach(gameObject, component, prepared) {
-        const useInstance = component.instanced !== false
-            && prepared.length === 1
-            && pluginRenderer3d.is3DSceneParent(gameObject)
-            && !pluginRenderer3d.has3DChildGameObjects(gameObject)
-            && !gameObject.getComponent(pluginRenderer3d.Transform3D)
-            && !this.threeContext.hasTransform3DRoot(gameObject.id);
-        const lastPose = poseKey(component.positionX, component.positionY, component.positionZ, component.rotationX, component.rotationY, component.rotationZ, component.scaleX, component.scaleY, component.scaleZ);
-        if (useInstance) {
-            const part = prepared[0];
-            const bucketKey = `${part.geoKey}|${part.matKey}`;
-            this.buckets?.add(bucketKey, gameObject.id, part.geometry, part.material, composePose(component.positionX, component.positionY, component.positionZ, component.rotationX, component.rotationY, component.rotationZ, component.scaleX, component.scaleY, component.scaleZ));
-            this.entries.set(gameObject.id, {
-                mode: 'instance',
-                bucketKey,
-                prepared,
-                lastPose,
-                poseBridge: new pluginRenderer3d.VisualPoseBridge(),
-            });
-            return;
-        }
-        this.attachGroup(gameObject, component, prepared, lastPose);
-    }
-    attachGroup(gameObject, component, prepared, lastPose) {
+    attachGroup(gameObject, component, prepared) {
         const group = new three.Group();
         const shadows = !!this.threeContext.shadows;
         for (const part of prepared) {
@@ -871,9 +684,9 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
             group.rotation.set(0, 0, 0);
             group.scale.set(1, 1, 1);
         }
+        const lastPose = poseKey(component.positionX, component.positionY, component.positionZ, component.rotationX, component.rotationY, component.rotationZ, component.scaleX, component.scaleY, component.scaleZ);
         this.threeContext.attachVisual(gameObject.id, group, gameObject);
         this.entries.set(gameObject.id, {
-            mode: 'group',
             group,
             prepared,
             lastPose,
@@ -891,12 +704,7 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
         const entry = this.entries.get(id);
         if (!entry)
             return;
-        if (entry.mode === 'instance' && entry.bucketKey) {
-            this.buckets?.remove(entry.bucketKey, id);
-        }
-        else if (entry.group) {
-            this.threeContext.detachVisual(id, entry.group);
-        }
+        this.threeContext.detachVisual(id, entry.group);
         this.releasePrepared(entry.prepared);
         this.entries.delete(id);
     }
@@ -905,7 +713,6 @@ let Graphics3DSystem = class Graphics3DSystem extends pluginRenderer3d.Renderer3
             this.handleRemove(id);
         }
         this.entries.clear();
-        this.buckets?.clear();
         this.geos.clear();
         this.mats.clear();
     }
@@ -919,7 +726,7 @@ Graphics3DSystem = tslib.__decorate([
             'rotationX', 'rotationY', 'rotationZ',
             'scaleX', 'scaleY', 'scaleZ',
             'opacity', 'roughness', 'metalness', 'emissive',
-            'map', 'doubleSide', 'material', 'instanced', 'parts',
+            'map', 'doubleSide', 'material', 'parts',
         ],
         Transform: ['_parent'],
     })