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

package/agent-skill.md

@@ -1,71 +1,38 @@
 # `@combos-fun/plugin-renderer-sprite-animation` — Agent notes
 
-Frame-based sprite animation for the 2D pipeline. Plays an ordered set of frames from a Texture Packer atlas as a flipbook animation.
-
-## When to read
-
-Read for any frame-by-frame animation: character idle / run / attack loops, FX, particle bursts.
-
-## Public API
+Read only for flipbook playback of atlas frames. Use `Sprite` when exactly one atlas frame should be shown.
 
 ```ts
-import { SpriteAnimation, SpriteAnimationSystem, type SpriteAnimationParams } from '@combos-fun/plugin-renderer-sprite-animation';
+import {
+  SpriteAnimation,
+  SpriteAnimationSystem,
+  type SpriteAnimationParams,
+} from '@combos-fun/plugin-renderer-sprite-animation';
 ```
 
-`componentName = 'SpriteAnimation'`, `systemName = 'SpriteAnimation'` (class is `SpriteAnimationSystem` — use `game.getSystem(SpriteAnimationSystem)`, not the string).
-
-### `SpriteAnimationParams`
+`SpriteAnimation.componentName = 'SpriteAnimation'`; `SpriteAnimationSystem.systemName = 'SpriteAnimation'`.
 
-| Field | Type | Default | Notes |
-|-------|------|---------|-------|
-| `resource` | `string` | — | Engine resource name registered with `RESOURCE_TYPE.SPRITE_ANIMATION`. `src` must include both `image` and `json`. |
-| `autoPlay` | `boolean?` | `false` | |
-| `speed` | `number?` | `100` | Milliseconds per frame |
-| `forwards` | `boolean?` | `true` | Direction |
+| Field | Type | Default |
+|---|---|---|
+| `resource` | `string` | required SPRITE_ANIMATION name |
+| `autoPlay` | `boolean?` | `true` |
+| `speed` | `number?` | `100` ms/frame |
+| `forwards` | `boolean?` | `false` |
 
-Methods: `play(times?)`, `stop()`, `gotoAndPlay(frame)`, `gotoAndStop(frame)`. Read-only getters: `currentFrame`, `totalFrames`. Events: `'complete'`, `'loop'`, `'frameChange'`.
+Importing the package registers SPRITE_ANIMATION atlas parsing. The implementation parses **all** entries in JSON `frames` and plays the resulting frame-key order. It rewrites JSON `animations` keys but does not expose a clip selector and does not choose an animation by clip name. Use separate resources if distinct clips need independent playback.
 
-Side effect: importing this package registers `SPRITE_ANIMATION` resource handlers on the engine `resource` singleton.
+Methods are `play(times?)`, `stop()`, `gotoAndPlay(frame)`, and `gotoAndStop(frame)`; getters are `currentFrame` and `totalFrames`. `play()`/`play(Infinity)` loops, `play(N > 0)` completes after N loops, and `play(0)` is a no-op. With finite playback, `forwards: true` stops on the last frame; otherwise it resets.
 
-## Required setup
+`play()` and `stop()` safely queue while the atlas loads. **`gotoAndPlay()` and `gotoAndStop()` do not queue and dereference the animation immediately, so calling them before async atlas readiness is unsafe.** Wait until the component has an animation/positive `totalFrames`.
 
-`RendererSystem` then `SpriteAnimationSystem`. Resource:
+Events are `'loop'`, `'frameChange'`, and `'complete'` (no payload is forwarded). `'complete'` from the Component's finite-loop logic does not occur during infinite playback.
 
 ```ts
-import { RESOURCE_TYPE, resource } from '@combos-fun/engine';
-
-resource.addResource([{
-  name: 'hero-run',
-  type: RESOURCE_TYPE.SPRITE_ANIMATION,
-  src: {
-    image: { type: 'png', url: 'https://cdn.example/hero-run.png' },
-    json: { type: 'json', url: 'https://cdn.example/hero-run.json' },
-  },
-  preload: true,
-}]);
+hero.addComponent(new SpriteAnimation({
+  resource: 'hero-run',
+  autoPlay: true,
+  speed: 80,
+}));
 ```
 
-JSON should be a Pixi spritesheet hash (`frames` name map + `meta.scale`).
-
-## Common pitfalls
-
-| Symptom | Fix |
-|---------|-----|
-| Animation doesn't start | `autoPlay: false` is the default — call `play()` from a Component lifecycle hook, or set `autoPlay: true` |
-| Imperative `play()` from bootstrap | ECS violation — wire the call from a Component's `start()` |
-| `src.<slot>.url is required` | That slot has no url |
-| `SpriteAnimation resource load error` | Files loaded but no frames after parse |
-| Stuck on first frame | Frames may be a single image; check JSON has multiple **named** `frames` entries |
-| Animation never completes | `play(0)` (or omitted `times`) loops forever; pass a positive integer for finite plays |
-| `'complete'` doesn't fire | Only fires when `play(N)` finishes N iterations; not when looping forever |
-
-## Minimal example
-
-```ts
-const hero = new GameObject('hero', { position: { x: 200, y: 400 }, size: { width: 108, height: 108 }, origin: { x: 0.5, y: 0.5 } });
-hero.addComponent(new SpriteAnimation({ resource: 'hero-run', autoPlay: true, speed: 80 }));
-```
-
-## Verification
-
-`pnpm --filter @combos-fun/plugin-renderer-sprite-animation run build`.
+Display width and height follow `Transform.size`, not frame pixels. Resource or speed changes are observed; `autoPlay` and `forwards` are not observer fields.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-sprite-animation",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "Frame-based sprite animation",
   "main": "index.js",
   "module": "dist/plugin-renderer-sprite-animation.esm.js",
@@ -37,10 +37,10 @@
   "author": "sun668 <q947692259@gmail.com>",
   "dependencies": {
     "pixi.js": "^8.18.1",
-    "@combos-fun/renderer-adapter": "0.0.44",
-    "@combos-fun/plugin-renderer": "0.0.44",
-    "@combos-fun/inspector-decorator": "0.0.44",
-    "@combos-fun/engine": "0.0.44"
+    "@combos-fun/engine": "0.0.46",
+    "@combos-fun/renderer-adapter": "0.0.46",
+    "@combos-fun/inspector-decorator": "0.0.46",
+    "@combos-fun/plugin-renderer": "0.0.46"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"