@combos-fun/plugin-renderer-sprite-animation 0.0.6 → 0.0.7

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/plugin-renderer-sprite-animation
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/plugin-renderer-sprite-animation — part of the Combos Fun engine monorepo.
+
+Keywords: `sprite`, `animation`, `flipbook`, `atlas`, `frame`, `2d`.
+
+## 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-sprite-animation/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-renderer-sprite-animation/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,67 @@
+# `@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
+
+```ts
+import { SpriteAnimation, SpriteAnimationSystem, type SpriteAnimationParams } from '@combos-fun/plugin-renderer-sprite-animation';
+```
+
+`componentName = 'SpriteAnimation'`, `systemName = 'SpriteAnimationSystem'`.
+
+### `SpriteAnimationParams`
+
+| 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 |
+
+Methods: `play(times?)`, `stop()`, `gotoAndPlay(frame)`, `gotoAndStop(frame)`.
+Read-only getters: `currentFrame`, `totalFrames`. Events:
+`'complete'`, `'loop'`, `'frameChange'`.
+
+Side effect: importing this package registers
+`SPRITE_ANIMATION` resource handlers on the engine `resource` singleton.
+
+## Required setup
+
+`RendererSystem` then `SpriteAnimationSystem`. Resource:
+
+```ts
+resource.addResource([{
+  name: 'hero-run',
+  src: { image: 'hero-run.png', json: 'hero-run.json' },
+  preload: true,
+}]);
+```
+
+## 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()` |
+| Stuck on first frame | Frames may be a single image; check JSON has multiple frame 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');
+hero.addComponent(new Transform({ position: { x: 200, y: 400 } }));
+hero.addComponent(new SpriteAnimation({ resource: 'hero-run', autoPlay: true, speed: 80 }));
+```
+
+## Verification
+
+`pnpm --filter @combos-fun/plugin-renderer-sprite-animation run build`.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-renderer-sprite-animation",
+  "pluginId": "renderer-sprite-animation",
+  "category": "rendering",
+  "dimension": "2d",
+  "isCore": false,
+  "keywords": ["sprite", "animation", "flipbook", "atlas", "frame", "2d"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer"],
+  "exports": ["SpriteAnimation", "SpriteAnimationSystem"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-sprite-animation",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "@combos-fun/plugin-renderer-sprite-animation",
   "main": "index.js",
   "module": "dist/plugin-renderer-sprite-animation.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.renderer.spriteAnimation.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-renderer-sprite-animation.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-renderer-sprite-animation.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-renderer-sprite-animation.d.ts",
   "keywords": [
     "combos-fun",
@@ -18,10 +32,10 @@
   "author": "sun668 <q947692259@gmail.com>",
   "dependencies": {
     "pixi.js": "^8.18.1",
-    "@combos-fun/plugin-renderer": "0.0.6",
-    "@combos-fun/inspector-decorator": "0.0.6",
-    "@combos-fun/renderer-adapter": "0.0.6",
-    "@combos-fun/engine": "0.0.6"
+    "@combos-fun/engine": "0.0.7",
+    "@combos-fun/plugin-renderer": "0.0.7",
+    "@combos-fun/renderer-adapter": "0.0.7",
+    "@combos-fun/inspector-decorator": "0.0.7"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"