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

package/agent-skill.md

@@ -1,57 +1,50 @@
 # `@combos-fun/plugin-renderer-3d-sprite-animation` — Agent notes
 
-Spritesheet animation projected onto a `PlaneGeometry` in 3D space. Animates UV offsets each frame. `resource` is an engine **name** (`RESOURCE_TYPE.SPRITE_ANIMATION` with both `src.image` and `src.json`), never a URL.
+Animates spritesheet UVs on a double-sided Three.js plane for effects, animated billboards, and flat characters.
 
-## When to read
-
-Read for any 2D-styled animation in a 3D scene: power-up effects, FX sprites, animated billboards, decals.
+Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, named resources, pose seeding, hierarchy, and stale-async handling.
 
 ## Public API
 
 ```ts
-import { SpriteAnimation3D, SpriteAnimation3DSystem, type SpriteAnimation3DParams } from '@combos-fun/plugin-renderer-3d-sprite-animation';
+import {
+  SpriteAnimation3D,
+  SpriteAnimation3DSystem,
+  type SpriteAnimation3DParams,
+} from '@combos-fun/plugin-renderer-3d-sprite-animation';
 ```
 
-`componentName = 'SpriteAnimation3D'`, `systemName = 'SpriteAnimation3DSystem'`.
+`componentName = 'SpriteAnimation3D'`; `systemName = 'SpriteAnimation3DSystem'`.
 
-### `SpriteAnimation3DParams`
+## Parameters
 
 | Field | Type | Default |
 |-------|------|---------|
-| `resource` | `string` | `''` (engine resource name, `RESOURCE_TYPE.SPRITE_ANIMATION`) |
+| `resource` | `string` | `''`; empty on ADD is a silent no-op |
 | `autoPlay` | `boolean` | `true` |
-| `speed` | `number` | `100` (ms per frame) |
-| `positionX` / `Y` / `Z` | `number` | `0` |
-| `rotationX` / `Y` / `Z` | `number` | `0` |
-| `scaleX` / `Y` | `number` | `1` (no `scaleZ` — plane is 2D) |
+| `speed` | `number` | `100` milliseconds per frame |
+| `positionX/Y/Z` | `number` | `0` |
+| `rotationX/Y/Z` | `number` | `0` radians |
+| `scaleX/Y` | `number` | `1` |
 
-The system reads `data.json` (`frames` array or name-map, plus `meta.size` when present) and `data.image`. It does **not** overwrite the 2D Pixi `SPRITE_ANIMATION` instance.
+There is no `scaleZ` and no public `play()`, `stop()`, or `gotoAndPlay()`.
 
-## Required setup
+## Resource and lifecycle
 
-`Renderer3DSystem` then `SpriteAnimation3DSystem`. Register both image and json slots:
+A `SPRITE_ANIMATION` resource needs both `src.image` and `src.json`. The system reads `data.image` and a top-level `data.json.frames`; `meta.size` is optional and falls back to image dimensions. It creates its own Three texture and does not overwrite the Pixi resource instance.
 
-```ts
-resource.addResource([{
-  name: 'explosion',
-  type: RESOURCE_TYPE.SPRITE_ANIMATION,
-  src: {
-    image: { type: 'png', url: 'https://cdn.example/explosion.png' },
-    json: { type: 'json', url: 'https://cdn.example/explosion.json' },
-  },
-  preload: true,
-}]);
-```
+Loading is async and validates the request before attachment. Resource replacement/removal invalidates old work and disposes an already-created stale texture. Removing an attached animation disposes geometry, material, and texture.
+
+`autoPlay` initializes the private `playing` flag only when the sheet loads; changing `autoPlay` later has no effect. `speed` is read every frame, so runtime changes affect the next frame interval without reloading. Changing `resource` rebuilds the entry.
+
+The first frame determines plane aspect ratio. Array frames retain array order; object-map frame keys are sorted lexically.
 
-## Common pitfalls
+## Package-specific pitfalls
 
-| Symptom | Fix |
-|---------|-----|
-| `Unknown resource` / missing json | Register `RESOURCE_TYPE.SPRITE_ANIMATION` with both `image` and `json` slots; do not pass a JSON URL to `resource` |
-| Animation never starts | `autoPlay` defaults to `true` |
-| Black plane / load error | JSON must have top-level `frames`; `meta.size` is optional (falls back to image size) |
-| Frames in wrong order | Hash `frames` keys are `Object.keys().sort()`; prefer array `frames` for playback order |
-| Stuck on first frame | Single-frame sheet; verify the JSON contains multiple frame entries |
+- Missing JSON, missing frames, or malformed `{ frame: { x, y, w, h } }` entries fail loading.
+- A one-frame sheet appears static.
+- Use an array when lexical filename sorting is not the desired sequence.
+- `speed` is a frame duration, not an FPS multiplier.
 
 ## Minimal example
 
@@ -67,4 +60,4 @@ fx.addComponent(new SpriteAnimation3D({
 
 ## Verification
 
-`pnpm --filter @combos-fun/plugin-renderer-3d-sprite-animation run build`.
+`pnpm --filter @combos-fun/plugin-renderer-3d-sprite-animation run build`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-sprite-animation",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "Spritesheet animation projected onto a PlaneGeometry in 3D space",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-sprite-animation.esm.js",
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "three": "^0.172.0",
-    "@combos-fun/engine": "0.0.44",
-    "@combos-fun/inspector-decorator": "0.0.44",
-    "@combos-fun/plugin-renderer-3d": "0.0.44"
+    "@combos-fun/engine": "0.0.46",
+    "@combos-fun/inspector-decorator": "0.0.46",
+    "@combos-fun/plugin-renderer-3d": "0.0.46"
   },
   "keywords": [
     "combos-fun",