feat: implement chromakey background support for improved transparency in sprite processing and animations

Author: freema

skills/pixel-art-generation/SKILL.md

@@ -17,6 +17,14 @@ Use PixelForge MCP tools to generate and process pixel art game assets.
 | `forge_thumbnail` | Game thumbnail/screenshot — uses reference sprites |
 | `process_sprite` | Post-process existing PNG — crop, bg removal, split |
 
+## Background Removal — IMPORTANT
+
+**Always use `background: "chromakey"` for sprites and animations.** This uses HSV-based green screen removal which is far more reliable than the old compositing equation approach.
+
+- `chromakey` — **BEST** — pure green #00FF00, HSV-based removal, clean edges, no artifacts
+- `black` / `white` — legacy compositing equation, can lose dark/light sprite pixels
+- Other colors — fallback to compositing equation
+
 ## Quick Start
 
 ### Single Sprite
@@ -25,20 +33,25 @@ forge_sprite
   description: "green slime enemy with horns and glowing eyes"
   outputPath: "public/assets/games/rpg/slime.png"
   style: "neon"
-  background: "black"
+  background: "chromakey"
 ```
 
-### Animation Frames
+### Animation Frames (Reference Chain — Default)
 ```
 forge_animation
   description: "green slime enemy"
   action: "bouncing up and down"
   frames: 4
+  frameDescriptions: ["idle resting on ground", "compressing flat", "stretching upward", "at peak of bounce"]
   outputPrefix: "public/assets/games/rpg/slime"
-  names: ["bounce-0", "bounce-1", "bounce-2", "bounce-3"]
+  names: ["idle", "compress", "stretch", "peak"]
   style: "neon"
+  background: "chromakey"
 ```
-Returns individual frame files: `slime-bounce-0.png`, `slime-bounce-1.png`, etc.
+
+**Reference chain mode (default):** Generates frame 0 first, then uses it as a reference image for all subsequent frames. This ensures consistent proportions, colors, and style across all frames. Each frame is a separate API call.
+
+To use the legacy sprite-sheet mode instead: `useReferenceChain: false`
 
 ### Background
 ```
@@ -58,6 +71,14 @@ forge_thumbnail
   aspect: "4:3"
 ```
 
+## Animation Best Practices
+
+1. **Always provide `frameDescriptions`** — explicit per-frame descriptions produce much better results than a generic action
+2. **Use `chromakey` background** — prevents transparency artifacts
+3. **Reference chain is default** — generates consistent frames by using frame 0 as reference
+4. **For inconsistent results, try `useReferenceChain: false` with `useTemplate: true`** — grid template mode as fallback
+5. **Keep frame count reasonable** — 3-4 frames per animation state is ideal
+
 ## Style Presets
 
 | Style | Best For | Look |
@@ -72,16 +93,15 @@ forge_thumbnail
 
 | Alias | Speed | Quality | Notes |
 |-------|-------|---------|-------|
-| `gemini-pro` | Medium | Best | Default — best for final assets |
+| `nano-banana` | Fast | Good | Default — best balance |
+| `pro` | Medium | Best | Best quality, use for hero assets |
 | `gemini-flash` | Fast | Good | Good for quick iteration |
-| `imagen` | Medium | High | Supports negative prompts |
-| `imagen-fast` | Fast | Good | Fastest option |
 
 ## Guidelines
 
-1. **forge_sprite and forge_animation auto-process** — output is always cropped, transparent, and ready to use
-2. **forge_background outputs raw** — no cropping, full size for game scenes
-3. **Use references for thumbnails** — pass actual game sprites so thumbnail matches the game's look
-4. **Choose aspect ratio wisely** — 1:1 for sprites, 4:3 for sheets, 3:4 or 16:9 for backgrounds
+1. **Always use `chromakey` background** for sprites and animations
+2. **forge_sprite and forge_animation auto-process** — output is always cropped, transparent, and ready to use
+3. **forge_background outputs raw** — no cropping, full size for game scenes
+4. **Use references for thumbnails** — pass actual game sprites so thumbnail matches the game's look
 5. **After generating, verify with Read tool** — Claude Code can display PNG files natively
 6. **Phaser sprite sizing** — generated images are large (~1000px), always use `setDisplaySize()` in game code

skills/sprite-processing/SKILL.md

@@ -14,10 +14,12 @@ Remove background and auto-crop:
 process_sprite
   inputPath: "raw-enemy.png"
   outputPath: "public/assets/games/rpg/enemy.png"
-  background: "black"
+  background: "chromakey"
   square: true
 ```
 
+**Prefer `chromakey` background** — uses HSV-based green screen removal. Much cleaner than black/white.
+
 ## Split Sprite Sheet
 
 Split a horizontal sprite sheet into individual frames:
@@ -27,7 +29,7 @@ process_sprite
   outputPath: "public/assets/games/rpg/hero"
   split: true
   names: ["idle", "walk-1", "walk-2", "attack"]
-  background: "white"
+  background: "chromakey"
   square: true
 ```
 Outputs: `hero-idle.png`, `hero-walk-1.png`, `hero-walk-2.png`, `hero-attack.png`
@@ -53,11 +55,20 @@ process_sprite
   skipCrop: true
 ```
 
+## Background Removal Methods
+
+| Background | Method | Best For |
+|-----------|--------|----------|
+| `chromakey` | HSV green screen | **BEST** — cleanest edges, no artifacts |
+| `black` | Compositing equation | Dark-themed sprites |
+| `white` | Compositing equation | Light-themed sprites |
+| `auto` | Edge detection | Unknown backgrounds |
+
 ## Options Reference
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `background` | auto-detect | `"black"`, `"white"`, or `"auto"` |
+| `background` | auto-detect | `"chromakey"`, `"black"`, `"white"`, or `"auto"` |
 | `threshold` | 20 | Color detection sensitivity (0-255) |
 | `square` | false | Pad output to square dimensions |
 | `padding` | 2 | Pixels of padding around content |

src/pipeline/background.ts

@@ -10,6 +10,7 @@ interface BgEntry {
 export const BG_COLOR_MAP: Record<Background, BgEntry> = {
   black: { rgb: { r: 0, g: 0, b: 0 }, hex: '#000000', name: 'black' },
   white: { rgb: { r: 255, g: 255, b: 255 }, hex: '#FFFFFF', name: 'white' },
+  chromakey: { rgb: { r: 0, g: 255, b: 0 }, hex: '#00FF00', name: 'chroma key green' },
   forest: { rgb: { r: 74, g: 103, b: 65 }, hex: '#4A6741', name: 'forest green' },
   sky: { rgb: { r: 74, g: 107, b: 138 }, hex: '#4A6B8A', name: 'sky blue' },
   dungeon: { rgb: { r: 42, g: 42, b: 42 }, hex: '#2A2A2A', name: 'dungeon gray' },
@@ -63,6 +64,9 @@ export function bgPromptFragment(bgKey: Background): string {
   if (bgKey === 'black' || bgKey === 'white') {
     return `Pure ${bgKey} background, completely flat solid ${bgKey} with no variation.`;
   }
+  if (bgKey === 'chromakey') {
+    return `Solid flat chroma key green background, EXACT hex #00FF00 (RGB 0, 255, 0) with NO gradients, NO noise, NO texture. The sprite must have a bold dark pixel outline 2-3 pixels wide around the entire shape.`;
+  }
   return `Solid ${entry.name} background (${entry.hex}), completely flat uniform color with no variation.`;
 }
 

src/pipeline/image-ops.ts

@@ -117,6 +117,95 @@ export function makeTransparentColor(
   return out;
 }
 
+/**
+ * HSV-based chromakey green background removal.
+ * Detects green pixels via Hue ±22° of 120°, Sat > 0.3, Val > 0.3
+ * and sets them transparent. Edge pixels get soft alpha via distance
+ * from the green hue center. Much more reliable than compositing eq.
+ */
+export function removeChromakeyGreen(
+  pixels: Buffer,
+  width: number,
+  height: number,
+): Buffer {
+  const out = Buffer.from(pixels);
+
+  for (let i = 0; i < width * height * 4; i += 4) {
+    const r = out[i]!;
+    const g = out[i + 1]!;
+    const b = out[i + 2]!;
+
+    // Convert RGB to HSV
+    const rn = r / 255;
+    const gn = g / 255;
+    const bn = b / 255;
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const delta = max - min;
+
+    let h = 0;
+    if (delta > 0) {
+      if (max === rn) h = 60 * (((gn - bn) / delta) % 6);
+      else if (max === gn) h = 60 * ((bn - rn) / delta + 2);
+      else h = 60 * ((rn - gn) / delta + 4);
+      if (h < 0) h += 360;
+    }
+    const s = max === 0 ? 0 : delta / max;
+    const v = max;
+
+    // Green detection: hue 98°-142° (120° ± 22°), sat > 0.3, val > 0.3
+    const hueCenter = 120;
+    const hueTolerance = 22;
+    const hueDist = Math.abs(h - hueCenter);
+
+    if (hueDist <= hueTolerance && s > 0.3 && v > 0.3) {
+      // Pure green background — fully transparent
+      out[i] = 0;
+      out[i + 1] = 0;
+      out[i + 2] = 0;
+      out[i + 3] = 0;
+    } else if (hueDist <= hueTolerance + 10 && s > 0.15 && v > 0.2) {
+      // Edge zone — soft alpha ramp based on distance from green
+      const edgeDist = Math.max(0, hueTolerance + 10 - hueDist) / 10;
+      const satFade = s > 0.3 ? 1.0 : (s - 0.15) / 0.15;
+      const fade = edgeDist * satFade;
+      const alpha = Math.max(0, 1 - fade);
+
+      if (alpha < 0.05) {
+        out[i] = 0;
+        out[i + 1] = 0;
+        out[i + 2] = 0;
+        out[i + 3] = 0;
+      } else {
+        out[i + 3] = Math.round(alpha * 255);
+      }
+    }
+    // else: keep pixel as-is (fully opaque, alpha stays 255)
+  }
+
+  // Edge softening: average alpha with 4 neighbors for smooth edges
+  const softened = Buffer.from(out);
+  for (let y = 1; y < height - 1; y++) {
+    for (let x = 1; x < width - 1; x++) {
+      const i = (y * width + x) * 4;
+      const a = out[i + 3]!;
+      // Only soften partially transparent edge pixels
+      if (a > 0 && a < 255) {
+        const neighbors = [
+          out[((y - 1) * width + x) * 4 + 3]!,
+          out[((y + 1) * width + x) * 4 + 3]!,
+          out[(y * width + x - 1) * 4 + 3]!,
+          out[(y * width + x + 1) * 4 + 3]!,
+        ];
+        const avg = (a + neighbors[0] + neighbors[1] + neighbors[2] + neighbors[3]) / 5;
+        softened[i + 3] = Math.round(avg);
+      }
+    }
+  }
+
+  return softened;
+}
+
 /**
  * Compositing-equation based soft alpha background removal.
  * Inspired by godogen's rembg_matting.py — produces smooth edges and
@@ -129,8 +218,8 @@ export function removeBackgroundColor(
   bg: BgColor,
   opts?: { noiseFloor?: number; solidThreshold?: number }
 ): Buffer {
-  const noiseFloor = opts?.noiseFloor ?? 0.08;
-  const solidThreshold = opts?.solidThreshold ?? 0.55;
+  const noiseFloor = opts?.noiseFloor ?? 0.06;
+  const solidThreshold = opts?.solidThreshold ?? 0.35;
   const out = Buffer.from(pixels);
 
   for (let i = 0; i < width * height * 4; i += 4) {
@@ -457,7 +546,7 @@ export function pixelateDownscale(
 
       const di = (dy * dstW + dx) * 4;
       const totalPixels = (sx2 - sx1) * (sy2 - sy1);
-      if (count > 0 && count >= totalPixels * 0.3) {
+      if (count > 0 && count >= totalPixels * 0.15) {
         // Enough opaque pixels — this is content
         out[di] = Math.round(r / count);
         out[di + 1] = Math.round(g / count);
@@ -480,13 +569,19 @@ export function processSpriteColor(
     skipCrop?: boolean;
     skipTransparent?: boolean;
     size?: number;
+    chromakey?: boolean;
   }
 ): ImageData {
   const pad = opts.padding ?? 2;
   let { width, height, pixels } = img;
 
   if (!opts.skipTransparent) {
-    pixels = removeBackgroundColor(pixels, width, height, bgColor);
+    // Use HSV chromakey removal for green backgrounds, compositing eq for others
+    if (opts.chromakey) {
+      pixels = removeChromakeyGreen(pixels, width, height);
+    } else {
+      pixels = removeBackgroundColor(pixels, width, height, bgColor);
+    }
   }
 
   if (!opts.skipCrop) {
@@ -564,6 +659,7 @@ export function splitAndProcess(
     expectedFrames?: number;
     maxSize?: number;
     bgColorHint?: BgColor;
+    chromakey?: boolean;
   }
 ): ImageData[] {
   const pad = opts.padding ?? 4;
@@ -606,8 +702,12 @@ export function splitAndProcess(
     const cy2 = Math.min(img.height, b.y2 + pad);
 
     let sprite = cropPixels(img.pixels, img.width, cx1, cy1, cx2, cy2);
-    // Use compositing-equation soft alpha for accurate bg removal
-    sprite.pixels = removeBackgroundColor(sprite.pixels, sprite.width, sprite.height, bgColor);
+    // Remove background: HSV chromakey for green, compositing equation for others
+    if (opts.chromakey) {
+      sprite.pixels = removeChromakeyGreen(sprite.pixels, sprite.width, sprite.height);
+    } else {
+      sprite.pixels = removeBackgroundColor(sprite.pixels, sprite.width, sprite.height, bgColor);
+    }
 
     // Tight crop to non-transparent pixels
     let x1t = sprite.width,

src/pipeline/prompt-builder.ts

@@ -55,6 +55,33 @@ export function detailHintForSize(size: number): string {
   return 'Detailed pixel art, fine features allowed, rich color palette.';
 }
 
+// ── Single animation frame prompt (reference-chain mode) ─────────────────
+
+export function buildAnimationFramePrompt(
+  description: string,
+  frameDescription: string,
+  isFirstFrame: boolean,
+  style: Style = 'clean',
+  bg: Background = 'black',
+  size: number = 48
+): string {
+  const bgEntry = BG_COLOR_MAP[bg];
+  const refNote = isFirstFrame
+    ? ''
+    : ' Must match the reference image exactly in style, proportions, colors, and outline thickness — only the pose/state changes.';
+  const parts = [
+    `${description}, ${frameDescription}.${refNote}`,
+    `${STYLE_PRESETS[style]}.`,
+    bgEntry ? `Centered on a solid ${bgEntry.name} (${bgEntry.hex}) background.` : '',
+    PIXEL_ART_CORE.join(', ') + '.',
+    SPRITE_RULES.join(', ') + '.',
+  ].filter(Boolean);
+  const hint = detailHintForSize(size);
+  if (hint) parts.push(hint);
+  parts.push(NEGATIVE_ALWAYS);
+  return parts.join(' ');
+}
+
 // ── Sprite prompt (godogen-simplified) ────────────────────────────────────
 
 export function buildSpritePrompt(