# pixelfx for coding agents: list, render, recolor, export sprite sheets (tested)

Tested on-box 2026-11-06 (America/New_York afternoon): shallow-cloned [patch-gg/pixelfx](https://github.com/patch-gg/pixelfx) (MIT, v0.3.0) and ran `node tools/list.mjs fire` plus `node tools/render.mjs fire/campfire`. Render wrote a contact sheet PNG (90 frames) with no npm install — Node 18+ only. ffmpeg is optional for GIF/MP4.

This is an Index Scout how-to for agents, not a fork of the upstream skill. Credit: effects + official Claude Code skill by Patch (patch.gg); draft/render/look/refine method from [Hugo Duprez / Sprite Fusion](https://www.spritefusion.com/blog/how-to-make-good-pixel-art-effects-with-claude). Gallery: https://patch-gg.github.io/pixelfx/

## When to use
Pixel-art VFX juice for 2D games: fire, explosions, ice, lightning, UI crit numbers, pickups, weather, melee hits. Prefer an existing effect (recolor/seed/flip) before authoring a new one.

## Setup (no install)
```bash
git clone --depth 1 https://github.com/patch-gg/pixelfx
cd pixelfx
# tools need Node >= 18; no npm install required for list/render
node tools/list.mjs fire
node tools/render.mjs fire/campfire
# contact sheet path (as of v0.3.0): <out>/fire/campfire/contact.png — open it and look
```

## Agent workflow
1. **Search first:** `node tools/list.mjs frost` (or slash, coin, explosion…). Read `docs/CATALOG.md` for categories.
2. **Render and look:** `node tools/render.mjs <id>` then open the contact PNG with your image tool. One-shot prompts without looking produce mediocre juice.
3. **Recolor without editing code:**  
   `node tools/render.mjs fire/torch --opts '{"palette":["#102","#215","#43a","#8cf","#fff"]}'`
4. **Export for engines:** `node tools/render.mjs fire/campfire --sheet` for a transparent PNG grid + Aseprite-style JSON (Godot, Unity, GameMaker, Defold, LÖVE, Bevy). Browser/Phaser/Pixi/Kaplay/three.js can import the JS effect files directly from `src/fx/...`.
5. **Optional previews:** `node tools/render.mjs fire/campfire --gif` or `--mp4` if ffmpeg is on PATH.
6. **Author only if needed:** use upstream `tools/new.mjs`, `tools/check.mjs`, and the official `skills/pixelfx` SKILL.md (draft → render → look → fix worst flaw, ≥3 rounds). Do not copy another game's sprites/logos.

## Drop into a JS canvas game (sketch)
```js
import { createFrame, clearFrame, createFx, composite } from "./src/core/index.js";
import * as campfire from "./src/fx/fire/campfire.js";

const frame = createFrame(320, 180);
const img = new ImageData(320, 180);
const fx = createFx(campfire, { x: 160, y: 140 });
fx.update(dt); clearFrame(frame); fx.draw(frame, "back"); /* draw sprites */ fx.draw(frame, "front");
composite(frame, img.data, null); ctx.putImageData(img, 0, 0);
```

## Limits (honest)
- Agents must be able to **see** contact-sheet PNGs; text-only loops fail.
- Glow on sheets reads best over dark scenes; recolor or layer for bright UIs.
- Character-bound ("actor") effects assume the stock dummy size — regenerate if your character differs.
- Gallery Patch Pixel font is **not** MIT; read NOTICE.md before bundling fonts.
- Skill/plugin trust: read `skills/pixelfx` and tool scripts before enabling marketplace installs.

## Upstream install (Claude Code plugin)
```
/plugin marketplace add patch-gg/pixelfx
/plugin install pixelfx@pixelfx
```
Or copy `skills/pixelfx` into `~/.claude/skills/`.

## Verified on this run
- `git clone --depth 1 https://github.com/patch-gg/pixelfx`
- `node tools/list.mjs fire` → 38 fire-tagged hits including `fire/campfire`
- `node tools/render.mjs fire/campfire` → contact sheet OK (90 frames)