@combos-fun/plugin-renderer-3d-material 0.1.14 → 0.1.16

package/agent-skill.md

@@ -1,79 +1,28 @@
 # `@combos-fun/plugin-renderer-3d-material` — Agent notes
 
-Replaces materials on meshes targeted within the same GameObject's 3D visual. Use one `Material3D` per GameObject for built-in Three materials or custom GLSL.
-
-Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, named resources, hierarchy, opacity scope, and stale-async handling.
-
-## Public API
-
-Runtime exports:
-
-```ts
-import {
-  Material3D,
-  Material3DSystem,
-  collectTargetMeshes,
-} from '@combos-fun/plugin-renderer-3d-material';
-```
-
-Type-only exports:
+Replaces materials on meshes in this GameObject. One `Material3D` per GameObject. Parent: `plugin-renderer-3d`. Register after the visual system.
 
 ```ts
-import type {
-  Material3DParams,
-  Material3DKind,
-  Material3DUniformValue,
-} from '@combos-fun/plugin-renderer-3d-material';
+import { Material3D, Material3DSystem } from '@combos-fun/plugin-renderer-3d-material';
 ```
 
-It is also valid to combine these in one import using the `type` modifiers. `Material3DKind` and `Material3DUniformValue` are types, not runtime values. `componentName = 'Material3D'`; `systemName = 'Material3DSystem'`.
-
-## Parameters
+`componentName = 'Material3D'`. `systemName = 'Material3DSystem'`.
 
-| Field | Type | Default |
-|-------|------|---------|
-| `type` | `'standard' \| 'basic' \| 'lambert' \| 'toon' \| 'physical' \| 'shader'` | `'standard'` |
-| `resource` | `string` | `''`; SHADER name for `shader` |
-| `node` | `string` | `''`; all target meshes |
-| `uniforms` | `Record<string, number \| boolean \| number[]>` | `{}` |
-| `color` | `number` | `0xffffff` |
-| `opacity` | `number` | `1` |
-| `roughness` / `metalness` | `number` | `1` / `0` |
-| `emissive` | `number` | `0` |
-| `wireframe` / `doubleSide` | `boolean` | `false` |
-| `map` | `string` | `''`; keep the source material's map |
+| Field | Default |
+| --- | --- |
+| `type` | `'standard'` — `standard \| basic \| lambert \| toon \| physical \| shader` |
+| `resource` | `''` — SHADER name when `type` is `shader` |
+| `node` | `''` — all meshes; matches own name or an ancestor |
+| `uniforms` | `{}` |
+| `color` | `0xffffff` |
+| `opacity` | `1` |
+| `roughness` / `metalness` | `1` / `0` |
+| `emissive` | `0` |
+| `wireframe` / `doubleSide` | `false` |
+| `map` | `''` — IMAGE name; empty keeps the source map |
 
-`node` matches a mesh whose own name or ancestor name equals the value. Instanced meshes are skipped. For non-model roots, traversal stops at nested `Transform3D` roots so a parent's material does not overwrite child GameObjects.
-
-## Runtime and lifecycle
-
-- Built-in material replacements copy the source texture maps; a non-empty `map` asynchronously loads an IMAGE override.
-- `shader` asynchronously loads a SHADER resource. A missing vertex shader uses the built-in UV vertex shader; a fragment shader is required.
-- Concurrent changes/removal invalidate pending shader or map work. Stale map textures are disposed. Removal restores original materials and disposes created materials/textures.
-- The system retries target discovery each frame, so a sibling `Model3D` can finish loading later.
-- `time` and `uTime` entries in `uniforms` receive elapsed seconds each renderer update; other values are copied, with booleans converted to `0`/`1`.
-- Built-in material classes retain normal skinned-mesh support. The default custom shader has no skinning logic.
-
-`Material3D.opacity` is the replacement material's value. A sibling `Render3D` subsequently overwrites every mesh material below that GameObject root each frame; use `Render3D.opacity` for root-wide live fades.
-
-## Package-specific pitfalls
-
-- Put `Material3DSystem` after the visual system so synchronous visuals exist first.
-- An unknown `type` falls back to `MeshStandardMaterial`.
-- A shader must implement any required skinning and texture sampling itself; setting `map` does not automatically add a map uniform to custom GLSL.
-
-## Minimal example
+Unknown `type` becomes `MeshStandardMaterial`. Built-in types keep skinned-mesh support and copy the source maps. `shader` needs a fragment shader; a missing vertex shader uses the built-in UV shader. `time` / `uTime` uniforms get elapsed seconds; booleans become `0` / `1`. Custom GLSL does not get skinning or an automatic map uniform. Instanced meshes are skipped. Traversal stops at nested `Transform3D` roots. Target meshes are retried each frame, so a sibling `Model3D` can finish loading later. Removal restores the original materials. A sibling `Render3D` overwrites opacity each frame.
 
 ```ts
-hero.addComponent(new Model3D({ resource: 'hero' }));
-hero.addComponent(new Material3D({
-  type: 'physical',
-  metalness: 0.8,
-  roughness: 0.2,
-  node: 'Armor',
-}));
+hero.addComponent(new Material3D({ type: 'physical', metalness: 0.8, roughness: 0.2, node: 'Armor' }));
 ```
-
-## Verification
-
-`pnpm --filter @combos-fun/plugin-renderer-3d-material run build`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-material",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Per-object 3D materials and custom shaders",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-material.esm.js",
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "three": "^0.172.0",
-    "@combos-fun/engine": "0.1.14",
-    "@combos-fun/inspector-decorator": "0.1.14",
-    "@combos-fun/plugin-renderer-3d": "0.1.14"
+    "@combos-fun/engine": "0.1.16",
+    "@combos-fun/inspector-decorator": "0.1.16",
+    "@combos-fun/plugin-renderer-3d": "0.1.16"
   },
   "keywords": [
     "combos-fun",