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

package/agent-skill.md

@@ -14,6 +14,14 @@ import {
   Renderer3D,
   Renderer3DManager,
   ThreeContext,
+  Transform3D,
+  Transform3DSystem,
+  Render3D,
+  Render3DSystem,
+  Camera3D,
+  Camera3DSystem,
+  Light3D,
+  Light3DSystem,
   tagObject3D,
   requireNamedResource,
   textureFromNamedImage,
@@ -33,6 +41,13 @@ 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`) |
+| `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.
 
@@ -43,9 +58,32 @@ Either `canvas` or `container` must be provided.
 - `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`
 
-There are **no separate camera or light plugins** — these come for free.
+`Graphics3D` / `Model3D` / `Img3D` meshes receive `castShadow` / `receiveShadow` only when `shadows: true`. `Model3D` traverses the loaded group and stamps every mesh.
+
+### Transform3D (pose + empty parents)
+
+`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.
+
+Empty parents work: `hero → hand → sword` does not need a mesh on `hand`.
+
+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
 
@@ -68,7 +106,7 @@ class MyRenderer3D extends Renderer3D {
 }
 ```
 
-Always call `tagObject3D(object, gameObject.id)` so `plugin-renderer-3d-event` can raycast the mesh.
+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)
 
@@ -96,11 +134,15 @@ This prevents memory leaks and double-add bugs when the same `GameObject` is re-
 ```ts
 new Game({
   systems: [
-    new Renderer3DSystem({ canvas, width: 750, height: 1334 }),
+    new Renderer3DSystem({ canvas, width: 750, height: 1334, shadows: true }),
+    new Transform3DSystem(),
+    new Render3DSystem(),
+    new Camera3DSystem(),
+    new Light3DSystem(),
     new Graphics3DSystem(),
     new Img3DSystem(),
     new Event3DSystem(),
-    // ...other 3D sub-systems, physics, audio
+    // Physics3DSystem + Physics3DConstraintSystem from @combos-fun/plugin-cannon
   ],
 });
 ```
@@ -108,7 +150,7 @@ new Game({
 ## Runtime behaviour
 
 - `ThreeContext` owns the render loop. `Renderer3D` subclasses register with `rendererManager` and are driven each frame.
-- Three.js `Object3D`s should always be attached to `this.threeContext.scene`, not directly to the renderer.
+- Three.js `Object3D`s should be attached with `attachVisual` / `attachObject3D`, not by calling `scene.add` in a plugin.
 
 ## Common pitfalls
 
@@ -116,11 +158,15 @@ new Game({
 |---------|-----|
 | 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 — adjust `position*` fields, or check camera distance (default `z=5`) |
+| 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
 
@@ -141,6 +187,20 @@ new Game({
 
 This alone shows an empty 3D scene with default lighting. Add `Graphics3DSystem` etc. and matching components to render anything.
 
+Empty parent / equipment slot:
+
+```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);
+```
+
 ## Verification
 
 - `pnpm --filter @combos-fun/plugin-renderer-3d run build`

package/combos-plugin.json

@@ -4,7 +4,7 @@
   "category": "rendering",
   "dimension": "3d",
   "isCore": false,
-  "keywords": ["three.js", "3d", "rendering", "webgl", "renderer-base", "scene"],
+  "keywords": ["three.js", "3d", "rendering", "webgl", "renderer-base", "scene", "transform3d", "camera", "light"],
   "agentSkill": "./agent-skill.md",
   "requires": ["@combos-fun/engine", "@combos-fun/inspector-decorator"],
   "exports": [
@@ -12,8 +12,17 @@
     "Renderer3D",
     "Renderer3DManager",
     "ThreeContext",
+    "Transform3D",
+    "Transform3DSystem",
+    "Render3D",
+    "Render3DSystem",
+    "Camera3D",
+    "Camera3DSystem",
+    "Light3D",
+    "Light3DSystem",
     "tagObject3D",
     "requireNamedResource",
-    "textureFromNamedImage"
+    "textureFromNamedImage",
+    "gameObjectIdFromIntersection"
   ]
 }