# sprite-animation-2d — 2D Sprite Sheet Animation

Play a sprite sheet animation at a configurable frame rate. Works with any sprite sheet generated by `playcraft image animate` or `playcraft image sprite-sheet`.

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `spriteSheetPath` | string | required | Path to the sprite sheet PNG |
| `frameWidth` | number | required | Width of each individual frame |
| `frameHeight` | number | required | Height of each individual frame |
| `frameCount` | number | required | Total number of frames |
| `columns` | number | required | Frames per row in the sheet |
| `fps` | number | 12 | Playback speed in frames per second |
| `loop` | boolean | true | Whether to loop the animation |
| `startFrame` | number | 0 | First frame to start playing from |
| `pingPong` | boolean | false | Reverse direction at end instead of looping |

## Workflow

1. Generate a sprite sheet:
   ```bash
   # From static image (built-in presets):
   playcraft image animate --input coin.png --preset spin --frames 8 --output coin_spin.png
   
   # From AI-generated frames:
   playcraft tools generate-image --prompt "coin sprite sheet 8 frames white background" --output coin_raw.png
   playcraft image sprite-sheet --inputs frame_*.png --output coin_spin.png --columns 4
   ```

2. Load in your engine using the reference code below.

## Engine References

- **PlayCanvas**: `ref/playcanvas.js` — uses `pc.Sprite` + `pc.AnimationComponent`
- **Phaser 3**: `ref/phaser.js` — uses `this.anims.create()` + `sprite.play()`
- **HTML5 Canvas**: `ref/html5.js` — uses `requestAnimationFrame` + `drawImage()`

## Decision Notes

| Decision | Reason |
|----------|--------|
| Sprite sheet over individual frames | Single asset load, better memory locality, no multi-file sync issues |
| Configurable fps | Different effects need different speeds (coin spin: 12fps, idle: 6fps) |
| Columns parameter | Flexible layout, not forced to square power-of-2 sheets |