@combos-fun/plugin-renderer-3d-model 0.0.6 → 0.0.7

package/README.md

@@ -0,0 +1,27 @@
+# @combos-fun/plugin-renderer-3d-model
+
+@combos-fun/plugin-renderer-3d-model — part of the Combos Fun engine monorepo.
+
+Keywords: `3d`, `model`, `glb`, `gltf`, `animation`, `mesh`.
+
+## Documentation
+
+- Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)
+- Machine-readable manifest: [`combos-plugin.json`](./combos-plugin.json)
+  (validated against `schemas/combos-plugin.schema.json` in the repo
+  root)
+- Entry skill (single source of truth for AI agents working with this
+  monorepo): `skills/combos-engine-development/SKILL.md`
+
+When consumed from npm, the manifest and agent notes are exposed as
+stable subpaths:
+
+```ts
+import manifest from '@combos-fun/plugin-renderer-3d-model/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-renderer-3d-model/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,73 @@
+# `@combos-fun/plugin-renderer-3d-model` — Agent notes
+
+GLB / GLTF 3D model loader and animator. Loads via `ThreeContext.loadGLB()`
+(GLTFLoader) and drives included animations through Three.js
+`AnimationMixer`.
+
+## When to read
+
+Read for any 3D character / prop / scenery model: loading GLB / GLTF
+files, choosing animation clips, scrubbing animation speed.
+
+## Public API
+
+```ts
+import { Model3D, GLBSystem, type Model3DParams } from '@combos-fun/plugin-renderer-3d-model';
+```
+
+`componentName = 'Model3D'`, `systemName = 'GLBSystem'`.
+
+### `Model3DParams`
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `resource` | `string` | `''` | GLB / GLTF URL (direct, not engine resource name) |
+| `autoPlay` | `boolean` | `true` | |
+| `animationIndex` | `number` | `0` | Index into the GLB's `animations` array |
+| `speed` | `number` | `1` | `AnimationMixer.timeScale` |
+| `positionX` / `Y` / `Z` | `number` | `0` |
+| `rotationX` / `Y` / `Z` | `number` | `0` |
+| `scaleX` / `Y` / `Z` | `number` | `1` |
+
+Changing `animationIndex` or `speed` restarts the animation cleanly.
+
+## Required setup
+
+`Renderer3DSystem` then `GLBSystem`. URL must be CORS-accessible and
+return valid binary GLB / JSON GLTF.
+
+## Runtime behaviour
+
+- Loading is async. While the GLB is loading, the GameObject has no
+  visible mesh.
+- The system uses `increaseAsyncId` / `validateAsyncId` to drop stale
+  loads if the component is removed mid-fetch.
+- The `AnimationMixer` is owned by the system; switching
+  `animationIndex` calls `mixer.stopAllAction()` then plays the new clip.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| Model not visible | Loaded at origin; adjust `position*` or check camera distance (camera is at z=5 by default) |
+| Wrong scale | Use `scaleX` / `Y` / `Z`; many GLBs export at meter scale |
+| Animation doesn't play | `autoPlay: true` is the default — check `animationIndex` is within `animations.length` |
+| Slow / stuttery animation | Lower-end GPU; reduce model polygon count or set `speed < 1` |
+| 404 / CORS | Verify URL returns valid GLB binary; check network tab |
+
+## Minimal example
+
+```ts
+const hero = new GameObject('hero');
+hero.addComponent(new Model3D({
+  resource: '/assets/hero.glb',
+  autoPlay: true,
+  animationIndex: 0,
+  speed: 1,
+  positionY: 0,
+}));
+```
+
+## Verification
+
+`pnpm --filter @combos-fun/plugin-renderer-3d-model run build`.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-renderer-3d-model",
+  "pluginId": "renderer-3d-model",
+  "category": "rendering",
+  "dimension": "3d",
+  "isCore": false,
+  "keywords": ["3d", "model", "glb", "gltf", "animation", "mesh"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer-3d"],
+  "exports": ["Model3D", "GLBSystem"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-model",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "@combos-fun/plugin-renderer-3d-model",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-model.esm.js",
@@ -9,13 +9,27 @@
   "types": "dist/plugin-renderer-3d-model.d.ts",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-renderer-3d-model.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-renderer-3d-model.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "dependencies": {
     "three": "^0.172.0",
-    "@combos-fun/engine": "0.0.6",
-    "@combos-fun/inspector-decorator": "0.0.6",
-    "@combos-fun/plugin-renderer-3d": "0.0.6"
+    "@combos-fun/engine": "0.0.7",
+    "@combos-fun/inspector-decorator": "0.0.7",
+    "@combos-fun/plugin-renderer-3d": "0.0.7"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"