# `@combos-fun/plugin-renderer-3d-sprite-animation` — Agent notes

Spritesheet animation projected onto a `PlaneGeometry` in 3D space. Animates UV offsets each frame to flip through frames from a Texture Packer JSON sheet.

## When to read

Read for any 2D-styled animation in a 3D scene: power-up effects, FX sprites, animated billboards, decals.

## Public API

```ts
import { SpriteAnimation3D, SpriteAnimation3DSystem, type SpriteAnimation3DParams } from '@combos-fun/plugin-renderer-3d-sprite-animation';
```

`componentName = 'SpriteAnimation3D'`, `systemName = 'SpriteAnimation3DSystem'`.

### `SpriteAnimation3DParams`

| Field | Type | Default |
|-------|------|---------|
| `resource` | `string` | `''` (Texture Packer JSON URL — direct) |
| `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) |

The system fetches the JSON URL directly (not an engine `resource` name). It reads top-level `frames` (array or name-map) and `meta.image` / `meta.size`. Image URL is resolved relative to the JSON path.

## Required setup

`Renderer3DSystem` then `SpriteAnimation3DSystem`. The JSON must reference a co-located image file.

## Common pitfalls

| Symptom | Fix |
|---------|-----|
| Animation never starts | `autoPlay` defaults to `true`; if you set `false`, drive `play()` from a Component lifecycle hook |
| Black plane / load error | JSON must have top-level `frames` plus `meta.image` and `meta.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 |

## Minimal example

```ts
const fx = new GameObject('explosion');
fx.addComponent(new SpriteAnimation3D({
  resource: '/assets/explosion.json',
  autoPlay: true,
  speed: 80,
  positionZ: -1,
}));
```

## Verification

`pnpm --filter @combos-fun/plugin-renderer-3d-sprite-animation run build`.