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

package/agent-skill.md

@@ -1,80 +1,31 @@
 # `@combos-fun/plugin-renderer-3d-model` — Agent notes
 
-Loads named 3D model resources and drives embedded clips with Three.js `AnimationMixer`. Supported runtime formats are GLB/glTF (Draco, KTX2, meshopt), FBX, OBJ with optional MTL, STL, DAE/Collada, and PLY. Prefer GLB; DCC source files are not runtime formats.
-
-Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, named resources, pose seeding, hierarchy, and the normal stale-async contract.
-
-## Public API and registration
+Named models and embedded clips. Parent: `plugin-renderer-3d`. Formats: GLB/glTF (Draco, KTX2, meshopt), FBX, OBJ+MTL, STL, DAE, PLY. Prefer GLB.
 
 ```ts
-import {
-  Model3D,
-  Model3DSystem,
-  type Model3DParams,
-  type ParsedModel,
-  type ModelResourceInstance,
-} from '@combos-fun/plugin-renderer-3d-model';
+import { Model3D, Model3DSystem } from '@combos-fun/plugin-renderer-3d-model';
 ```
 
-`componentName = 'Model3D'`; `systemName = 'Model3DSystem'`.
-The standard package entry loads `Model3DSystem`, whose `parseModel` import
-registers `RESOURCE_TYPE.MODEL` and `GLB`. Deep-importing only the component
-bypasses that registration.
-
-## Parameters
-
-| Field | Type | Default | Behavior |
-|-------|------|---------|----------|
-| `resource` | `string` | `''` | MODEL name; empty on ADD is a silent no-op |
-| `autoPlay` | `boolean` | `true` | Consulted only when a newly loaded model is attached; it is not a runtime play/pause control |
-| `animationIndex` | `number` | `0` | Index into `animations` |
-| `speed` | `number` | `1` | Assigned to the selected action's `timeScale` |
-| `positionX/Y/Z` | `number` | `0` | Local pose compatibility fields |
-| `rotationX/Y/Z` | `number` | `0` | Radians |
-| `scaleX/Y/Z` | `number` | `1` | Model scale |
+`componentName = 'Model3D'`. `systemName = 'Model3DSystem'`. Import the package entry so `RESOURCE_TYPE.MODEL` is registered.
 
-`autoPlay` is not observed after load. By contrast, changing either `animationIndex` **or** `speed` at runtime always calls `playAnimation`: all actions are stopped and the selected clip is restarted at the requested speed, even when `autoPlay` is false. An out-of-range index therefore stops current playback and starts nothing.
+| Field | Default | |
+| --- | --- | --- |
+| `resource` | `''` | MODEL name. Empty on add does nothing |
+| `autoPlay` | `true` | only when the model attaches |
+| `animationIndex` | `0` | |
+| `speed` | `1` | `timeScale` |
+| `position*` / `rotation*` / `scale*` | `0` / `0` / `1` | |
 
-## Resource shape
-
-Use a `model`, `glb`, or `gltf` source slot; parsed data may likewise be in `data.model`, `data.glb`, or `data.gltf`. OBJ may add an `mtl` slot. Relative glTF/OBJ sidecars are resolved from the main asset directory.
+Changing `animationIndex` or `speed` restarts that clip, even when `autoPlay` is false. An out-of-range index stops playback. Load is async. Removing or replacing during parse can leave a stale clone.
 
 ```ts
 resource.addResource([{
   name: 'hero',
   type: RESOURCE_TYPE.MODEL,
-  src: { model: { type: 'glb', url: 'https://cdn.example/hero.glb' } },
+  src: { model: { type: 'glb', url } },
   preload: true,
 }]);
+hero.addComponent(new Model3D({ resource: 'hero' }));
 ```
 
-## Runtime and lifecycle
-
-- Parsing is async; no model is visible until it completes. Parsed resources are cached, then each GameObject receives a `SkeletonUtils.clone`.
-- Each attached animated clone gets its own mixer in `ThreeContext`.
-- `resource` replacement removes the prior model and loads a new clone. Removal stops its mixer and disposes clone geometry/materials.
-- Unlike the normal parent contract, async-id validation happens after attachment; removing or replacing the component during parsing can leave a stale clone attached.
-- Renderer shadows traverse every mesh in the clone.
-
-## Package-specific pitfalls
-
-- OBJ/STL/PLY commonly have no animation clips.
-- Draco and KTX2 decoder assets are fetched from the configured Google/unpkg CDN paths, so CSP/network access must allow them.
-- Exported model units vary; adjust `scaleX/Y/Z`.
-- A sibling `Material3D` can override clone materials after load.
-- A sibling Cannon `Physics3D` may derive an AABB/hull after load. Use trimesh only for static scenery; animation does not rebuild a collider.
-
-## Minimal example
-
-```ts
-hero.addComponent(new Model3D({
-  resource: 'hero',
-  autoPlay: true,
-  animationIndex: 0,
-  speed: 1,
-}));
-```
-
-## Verification
-
-`pnpm --filter @combos-fun/plugin-renderer-3d-model run build`
+OBJ may add an `mtl` slot. `glb` / `gltf` slots are also accepted. Relative glTF/OBJ sidecars resolve from the asset directory. Deep-importing only the component skips registration. OBJ/STL/PLY usually have no clips. Draco/KTX2 decoders load from CDN. Units vary; set `scale*`. Sibling `Material3D` overrides materials. Sibling `Physics3D` can build `aabb` / `hull` after load; `trimesh` is static only. Animation does not rebuild a collider. Each clone has its own mixer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-model",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Named 3D model loader (glTF/GLB, FBX, OBJ, STL, Collada, PLY) and animator",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-model.esm.js",
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "three": "^0.172.0",
-    "@combos-fun/engine": "0.1.14",
-    "@combos-fun/plugin-renderer-3d": "0.1.14",
-    "@combos-fun/inspector-decorator": "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",