@combos-fun/plugin-renderer-3d 0.0.44 → 0.0.46

package/agent-skill.md

@@ -1,33 +1,39 @@
 # `@combos-fun/plugin-renderer-3d` — Agent notes
 
-3D rendering foundation for Combos Fun. Wraps Three.js (`three` ^0.172) and exposes `Renderer3DSystem`, the `Renderer3D` base class, and a `ThreeContext` that owns the Three.js scene / camera / lights / WebGL renderer / `Clock`.
+3D rendering foundation for Combos Fun, backed by Three.js (`three` ^0.172). Read this before any `plugin-renderer-3d-*` leaf skill; shared setup, resource, pose, and stale-async rules live here.
 
-## When to read
+## 3D drawable picker
 
-Read for any 3D rendering task: setting up the canvas, blank-3D-canvas debugging, custom 3D renderer plugins, async asset loading. All `plugin-renderer-3d-*` sub-plugins assume this file is already loaded.
+- Procedural primitive, including a texture-mapped primitive → `Graphics3D`
+- One image on one plane → `Img3D`
+- GLB / glTF / FBX / OBJ / STL / DAE / PLY asset → `Model3D`
+- Repeated UV texture on a plane → `TilingSprite3D`
+- Spritesheet animation on a plane → `SpriteAnimation3D`
+- Replace or override materials on an existing visual → sibling `Material3D`
 
 ## Public API
 
+The current package entry exports these runtime values:
+
 ```ts
 import {
-  Renderer3DSystem,
-  Renderer3D,
-  Renderer3DManager,
-  ThreeContext,
-  Transform3D,
-  Transform3DSystem,
-  Render3D,
-  Render3DSystem,
-  Camera3D,
-  Camera3DSystem,
-  Light3D,
-  Light3DSystem,
-  tagObject3D,
-  requireNamedResource,
-  textureFromNamedImage,
+  Renderer3DSystem, ThreeContext, Renderer3D, Renderer3DManager,
+  Transform3D, Transform3DSystem,
+  Render3D, Render3DSystem,
+  Camera3D, Camera3DSystem,
+  Light3D, Light3DSystem,
+  COMBOS_GAME_OBJECT_ID, COMBOS_TRANSFORM3D,
+  tagObject3D, gameObjectIdFromObject3D, gameObjectIdFromIntersection,
+  isTransform3DRoot,
+  requireNamedResource, textureFromNamedImage, textureFromResourceImage,
+  is3DSceneParent, has3DChildGameObjects,
+  readPose, poseKeyOf, copyPose, isIdentityPose, seedTransform3D,
+  VisualPoseBridge,
 } from '@combos-fun/plugin-renderer-3d';
 ```
 
+Type-only exports are `Renderer3DSystemParams`, `ThreeContextParams`, `FogParams`, `HemisphereLightParams`, `ToneMappingKind`, `Transform3DLike`, `Transform3DParams`, `Render3DParams`, `Camera3DParams`, `Light3DParams`, `Light3DKind`, and `PoseLike`.
+
 ### `Renderer3DSystem`
 
 `systemName = 'Renderer3DSystem'`. Init params:
@@ -41,95 +47,21 @@ import {
 | `antialias` | `boolean` | `true` |
 | `backgroundColor` | `number` | `0x000000` |
 | `backgroundAlpha` | `number` | `1` |
-| `fog` | `false` or `{ color?, near?, far? }` | off |
-| `hemisphereLight` | `false` or `{ skyColor?, groundColor?, intensity? }` | on (`0xffffff` / `0x444444` / `0.35`) |
+| `fog` | `boolean \| { color?, near?, far? }` | `false`; object defaults: background color / `8` / `40` |
+| `hemisphereLight` | `boolean \| { skyColor?, groundColor?, intensity? }` | on; `0xffffff` / `0x444444` / `0.35` |
 | `shadows` | `boolean` | `false` |
 | `toneMapping` | `'none' \| 'aces' \| 'linear' \| 'reinhard' \| 'cineon'` | `'aces'` |
 | `toneMappingExposure` | `number` | `1` |
 | `ambientIntensity` | `number` | `0.6` |
 | `directionalIntensity` | `number` | `0.8` |
 
-Either `canvas` or `container` must be provided.
-
-### Built-in scene defaults
-
-`ThreeContext` automatically creates:
-
-- `PerspectiveCamera` (FOV 75, z=5)
-- `AmbientLight` (`0xffffff`, intensity `0.6`)
-- `DirectionalLight` (`0xffffff`, intensity `0.8`, position `(5, 10, 7.5)`)
-- `HemisphereLight` (disable with `hemisphereLight: false`)
-- `ACESFilmicToneMapping` (set `toneMapping: 'none'` to turn off)
-- Optional `Fog` / shadow maps when those params are set
-- `WebGLRenderer`, `Clock`
-
-`Graphics3D` / `Model3D` / `Img3D` meshes receive `castShadow` / `receiveShadow` only when `shadows: true`. `Model3D` traverses the loaded group and stamps every mesh.
-
-### Transform3D (pose + empty parents)
+Pass `canvas` to reuse an element. With no `canvas`, `container` appends the newly created renderer canvas; with neither, the canvas is created but not mounted. Defaults also include a perspective camera (FOV `75`, near `0.1`, far `1000`, z=`5`), ambient light, directional light at `(5, 10, 7.5)`, hemisphere light, `WebGLRenderer`, and `Clock`.
 
-`Transform3D` is the 3D pose source of truth (`position*` / `rotation*` / `scale*`, plus read-only `worldPosition*` / `worldRotation*`). `Renderer3DSystem` auto-adds `Transform3D` on every `Transform` ADD except the Scene itself, and creates a Three.js `Group` root. Visuals (`Graphics3D`, `Model3D`, …) hang under that Group via `attachVisual` — they no longer replace the root.
+## Shared contracts for every leaf plugin
 
-Empty parents work: `hero → hand → sword` does not need a mesh on `hand`.
+### System order
 
-Child `Transform3D` / visual `position*` are **local**. A `Graphics3D` that is instanced is converted to a `Group` when it gains a parent, children, or a `Transform3D` root.
-
-`Physics3D.update()` writes pose back onto sibling `Transform3D` (and other `position*` components).
-
-### Render3D / Camera3D / Light3D
-
-| Component | System | Role |
-|-----------|--------|------|
-| `Render3D` | `Render3DSystem` | `visible`, `opacity` (2D `alpha`), `renderOrder` (2D `zIndex`), `sortableChildren` |
-| `Camera3D` | `Camera3DSystem` | `fov` / `near` / `far` / `active` / optional `lookAt`. Pose is `Transform3D`. First camera without a pose is placed at `z=5`. No `Camera3D` → keep the default `PerspectiveCamera`. |
-| `Light3D` | `Light3DSystem` | `ambient` / `directional` / `hemisphere` / `point` / `spot`. **The first `Light3D` removes the built-in default lights.** |
-
-Register those systems after `Renderer3DSystem`. `Transform3DSystem` is optional (the renderer already creates roots) but recommended so pose stays in the Transform3D system.
-
-### `Renderer3D` base class
-
-Extend this for any custom 3D rendering plugin:
-
-```ts
-class MyRenderer3D extends Renderer3D {
-  init() {
-    this.rendererSystem = this.game.getSystem(Renderer3DSystem);
-    this.rendererSystem.rendererManager.register(this);
-  }
-  componentChanged(changed) {
-    const scene = this.threeContext.scene;
-    /* create / update / dispose THREE.Object3D under scene */
-    tagObject3D(object3d, changed.gameObject.id);
-  }
-  rendererUpdate(gameObject) {
-    /* per-frame sync */
-  }
-}
-```
-
-Always call `tagObject3D(object, gameObject.id)` so `plugin-renderer-3d-event` can raycast the mesh. Attach visuals with `this.threeContext.attachVisual(id, object, gameObject)` so they parent under the `Transform3D` Group.
-
-### Named resources (same as 2D)
-
-3D `Img3D` / `Model3D` / `TilingSprite3D` / `SpriteAnimation3D` take an engine **resource name**. Register with `resource.addResource` (`RESOURCE_TYPE.IMAGE` / `MODEL` / `SPRITE_ANIMATION`). Put CDN URLs in `src`, not on the component. A missing name throws; there is no `http` / `./` / `/` fallback.
-
-Use `requireNamedResource(name)` and `textureFromNamedImage(name)` from this package. 3D image systems read `data.image` (and `data.json` for spritesheets) so they do not overwrite 2D Pixi `registerInstance(IMAGE)`.
-
-### Async loading pattern
-
-For 3D plugins that load assets (`Img3D`, `Model3D`, etc.) use the inherited helpers to drop stale work when a component is removed mid-load:
-
-```ts
-const asyncId = this.increaseAsyncId(gameObject.id);
-const data = await loadSomething();
-if (!this.validateAsyncId(gameObject.id, asyncId)) return; // stale
-/* attach data */
-```
-
-This prevents memory leaks and double-add bugs when the same `GameObject` is re-used quickly.
-
-## Required setup
-
-`Renderer3DSystem` **must** be the first system added before any 3D sub-system that calls `getSystem(Renderer3DSystem)` in `init`. For taps, also register `Event3DSystem` from `@combos-fun/plugin-renderer-3d-event`.
+`Renderer3DSystem` must precede every 3D leaf system because each leaf registers with its `rendererManager` during `init`. Add `Transform3DSystem`, `Render3DSystem`, camera/light systems, drawable systems, then overlays such as `Material3DSystem`; add `Event3DSystem` for picking. `Transform3DSystem` is optional for root creation because `Renderer3DSystem` also ensures roots, but it remains the normal pose system.
 
 ```ts
 new Game({
@@ -141,68 +73,66 @@ new Game({
     new Light3DSystem(),
     new Graphics3DSystem(),
     new Img3DSystem(),
+    new Material3DSystem(),
     new Event3DSystem(),
-    // Physics3DSystem + Physics3DConstraintSystem from @combos-fun/plugin-cannon
   ],
 });
 ```
 
-## Runtime behaviour
+### Named resources
 
-- `ThreeContext` owns the render loop. `Renderer3D` subclasses register with `rendererManager` and are driven each frame.
-- Three.js `Object3D`s should be attached with `attachVisual` / `attachObject3D`, not by calling `scene.add` in a plugin.
+`resource` fields contain an engine resource **name**, not a URL or path. Register the appropriate `RESOURCE_TYPE` with `resource.addResource`; URLs belong in `src`. There is no URL fallback. `requireNamedResource` rejects empty or unknown names. Asset components currently skip ADD when their own `resource` is empty; image helpers build a Three `Texture` from `data.image`, leaving the 2D Pixi resource instance alone.
 
-## Common pitfalls
+### Pose and hierarchy
 
-| Symptom | Fix |
-|---------|-----|
-| Blank canvas | Add `Renderer3DSystem`; ensure `autoStart: true` or call `game.start()` |
-| Nothing draws | Add the matching 3D sub-system (`Graphics3DSystem`, `Model3DSystem`, etc.) before adding components |
-| Object loaded but not visible | Object likely loaded at origin — set `Transform3D.position*` (or sibling visual `position*`, which seeds `Transform3D`), or check camera distance (default `z=5`) |
-| Empty parent / hand slot has no child | Add `Transform3DSystem` or rely on `Renderer3DSystem` auto-`Transform3D`; `addChild` the slot then the item |
-| Custom lights + still have default sun | First `Light3D` removes defaults — add `Light3DSystem` |
-| Want 2D-like hide / fade / draw order | `Render3D` + `Render3DSystem` (`visible` / `opacity` / `renderOrder`) |
-| `getSystem` undefined | Use class reference `game.getSystem(Renderer3DSystem)` |
-| Memory leak after fast remove | Use `increaseAsyncId` / `validateAsyncId` to drop stale async work |
-| CORS errors loading 3D assets | Host on same origin or CORS-enabled CDN; URLs live in `addResource` `src` |
-| `tap` never fires | Use `Event3D` + `Event3DSystem`, not 2D `Event` |
-| Instanced primitives not pickable | `gameObjectIdFromIntersection` reads `instanceId`; official `Graphics3DSystem` fills `userData.combosInstanceGameObjectIds` |
-
-## Minimal example
+`Transform3D` is the pose source of truth (`position*`, `rotation*`, `scale*`, plus computed world position/rotation). A Three `Group` root is created per non-Scene GameObject, so empty parents and local child transforms work.
 
-```ts
-import { Game } from '@combos-fun/engine';
-import { Renderer3DSystem } from '@combos-fun/plugin-renderer-3d';
+Leaf visual pose fields are compatibility inputs. On first bridge sync, a non-identity visual pose seeds an identity sibling `Transform3D`; the visual object is then reset to identity under that root. Prefer writing `Transform3D` after setup. `attachVisual` tags the visual and parents it under the root; use it instead of `scene.add`.
 
-new Game({
-  systems: [
-    new Renderer3DSystem({
-      canvas: document.querySelector('#canvas')!,
-      width: 750,
-      height: 1334,
-    }),
-  ],
-});
-```
-
-This alone shows an empty 3D scene with default lighting. Add `Graphics3DSystem` etc. and matching components to render anything.
+### Async lifecycle
 
-Empty parent / equipment slot:
+Asset-loading systems use a per-GameObject async id to reject stale work after
+removal, replacement, or resource changes:
 
 ```ts
-const hero = new GameObject('hero');
-hero.addComponent(new Transform3D({ positionY: 1 }));
-hero.addComponent(new Graphics3D({ shape: 'box', width: 0.6, height: 1.2, depth: 0.4 }));
-const hand = new GameObject('hand');
-hand.addComponent(new Transform3D({ positionX: 0.4, positionY: 0.3 }));
-const sword = new GameObject('sword');
-sword.addComponent(new Graphics3D({ shape: 'box', width: 0.1, height: 0.8, depth: 0.1, color: 0xcccccc }));
-hero.addChild(hand);
-hand.addChild(sword);
+const asyncId = this.increaseAsyncId(gameObject.id);
+const asset = await loadSomething();
+if (!this.validateAsyncId(gameObject.id, asyncId)) return;
 ```
 
+Dispose assets created by rejected work. `Model3DSystem` is an exception: it
+validates after attachment, so its skill documents the stale-clone risk.
+
+## Core components
+
+| Component | Defaults and behavior |
+|-----------|-----------------------|
+| `Render3D` | `visible: true`, `opacity: 1`, `renderOrder: 0`, `sortableChildren: false`. Every renderer update, `opacity` is written to **every mesh material under this GameObject's registered root Object3D subtree** (including nested child visuals), so it overrides visual/`Material3D` opacity for that frame. |
+| `Camera3D` | Controls `fov`, `near`, `far`, `active`; `lookAt` is boolean with `lookAtX/Y/Z`. Without one, the fallback camera remains active. |
+| `Light3D` | `type` defaults to `'directional'`; supports color/intensity/shadows and type-specific fields. The first `Light3D` removes all built-in default lights. |
+
+When `shadows: true`, official drawable systems mark their meshes `castShadow` and `receiveShadow`; `Model3D` traverses the loaded clone.
+
+## Custom renderer plugins
+
+Extend `Renderer3D`, register it with `Renderer3DSystem.rendererManager`, handle observer changes in `componentChanged`, and do frame sync in `rendererUpdate`. `attachVisual(id, object, gameObject)` both tags and parents a visual. Use `tagObject3D` yourself only when bypassing that helper.
+
+The engine owns the loop: `Renderer3DSystem.update()` applies `Transform3D` and invokes leaf `rendererUpdate`; `lateUpdate()` advances animation mixers and renders the frame.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| Blank canvas | Add `Renderer3DSystem`; mount its canvas; ensure the game starts |
+| Nothing draws | Add the matching leaf system before adding its component |
+| Loaded object is invisible | Check `Transform3D`, camera distance, front/back side, lights, and resource errors |
+| `getSystem` is undefined | Use `game.getSystem(Renderer3DSystem)` or exact string `'Renderer3DSystem'` |
+| Fast remove/re-add leaks or double-adds | Follow the async-id invalidation pattern |
+| CORS failure | Serve assets from the same origin or a CORS-enabled URL registered in `src` |
+
+Key 2D/3D differences: use `Render3D.opacity` rather than `Render.alpha`, `Event3D`/`Event3DSystem` rather than `Event`/`EventSystem`, and Cannon (`plugin-cannon`) rather than Matter for 3D physics.
+
 ## Verification
 
 - `pnpm --filter @combos-fun/plugin-renderer-3d run build`
-- Run a 3D example app and check the browser console for Three.js / WebGL
-  errors and missing assets.
+- Run a 3D example and inspect WebGL/resource errors in the browser console.

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

@@ -6,7 +6,6 @@ var three = require('three');
 var inspectorDecorator = require('@combos-fun/inspector-decorator');
 
 const COMBOS_GAME_OBJECT_ID = 'combosGameObjectId';
-const COMBOS_INSTANCE_GAME_OBJECT_IDS = 'combosInstanceGameObjectIds';
 const COMBOS_TRANSFORM3D = 'combosTransform3D';
 function isTransform3DRoot(object) {
     return !!object?.userData?.[COMBOS_TRANSFORM3D];
@@ -28,21 +27,9 @@ function gameObjectIdFromObject3D(object) {
     }
     return undefined;
 }
-/** Resolve a raycast hit, including InstancedMesh `instanceId` rows. */
+/** Resolve a raycast hit to a GameObject id. */
 function gameObjectIdFromIntersection(intersection) {
-    if (!intersection?.object)
-        return undefined;
-    if (typeof intersection.instanceId === 'number') {
-        let current = intersection.object;
-        while (current) {
-            const ids = current.userData?.[COMBOS_INSTANCE_GAME_OBJECT_IDS];
-            if (Array.isArray(ids) && typeof ids[intersection.instanceId] === 'number') {
-                return ids[intersection.instanceId];
-            }
-            current = current.parent;
-        }
-    }
-    return gameObjectIdFromObject3D(intersection.object);
+    return gameObjectIdFromObject3D(intersection?.object);
 }
 
 /** True when this GameObject is a scene root (no 3D parent). */
@@ -684,7 +671,7 @@ var Renderer3DSystem = Renderer3DSystem$1;
 /** Auto-generated by scripts/build-package.mjs — do not edit. */
 Object.assign(Renderer3DSystem, {
     packageName: "@combos-fun/plugin-renderer-3d",
-    packageVersion: "0.0.44",
+    packageVersion: "0.0.46",
 });
 
 class Renderer3D extends engine.System {
@@ -1225,7 +1212,6 @@ async function textureFromNamedImage(name) {
 }
 
 exports.COMBOS_GAME_OBJECT_ID = COMBOS_GAME_OBJECT_ID;
-exports.COMBOS_INSTANCE_GAME_OBJECT_IDS = COMBOS_INSTANCE_GAME_OBJECT_IDS;
 exports.COMBOS_TRANSFORM3D = COMBOS_TRANSFORM3D;
 exports.Camera3D = Camera3D;
 exports.Camera3DSystem = Camera3DSystem_default;