---
name: pixelforge-character-sprites
description: >
  Generate, download, and wire recognizable 4-direction 2D RPG walk-cycle character sprite
  packs from a portrait photo (or grab the free CC0 starter pack) via PixelForge (https://pixel-forge.net).
  Outputs 96x96 & 48x48 4x4 PNG sheets, 32 frames, 8 strips, RPG Maker MV/MZ $character.png,
  Phaser 3 JSON atlases, and schema-v2 manifest.json for Godot 4, Unity 6, Phaser 3, RPG Maker,
  Pygame, and HTML5 Canvas.
---

# PixelForge Agent Skill (`pixel-forge.net`)

Use this skill whenever a user building a 2D or vibe-coded game wants:
1. A **free working 4-direction character sprite pack** to scaffold player movement immediately, or
2. To turn a **real person's portrait photo** into a recognizable, baseline-aligned 4-direction character sprite pack ($5 one-time via Stripe Checkout).

## 1. Zero-Cost Scaffolding First (Recommended Default)

Before asking the user to pay $5, verify your game's movement, scaling, and animation loop with the **free unblocked production starter pack** (identical schema-v2 layout, commercial/CC0 safe):

```bash
mkdir -p assets/player
curl -fsSL https://pixel-forge.net/samples/starter-pack.zip -o /tmp/pf-starter.zip
unzip -qo /tmp/pf-starter.zip -d assets/player
cat assets/player/manifest.json
```

## 2. Forging a Custom Photo ($5 Stripe Checkout Handoff)

PixelForge has no accounts or API keys required for single-character orders. Agents upload the photo via `POST /api/jobs` (`Accept: application/json`), hand the returned `checkout_url` to the human user to approve the $5 Stripe payment, then poll `status_url` until `status == "complete"`:

```bash
# Step A: Upload portrait (JPEG, PNG, WebP, or HEIC <= 12MB)
RESP=$(curl -fsSL -X POST https://pixel-forge.net/api/jobs \
  -H "Accept: application/json" \
  -F "photo=@./portrait.jpg" \
  -F "notes=keep glasses and navy hoodie")
echo "$RESP"
# -> {"ok":true,"job_id":"...","status":"checkout_created","checkout_url":"https://checkout.stripe.com/...","status_url":"https://pixel-forge.net/api/jobs/...","download_url":"https://pixel-forge.net/api/jobs/.../download"}
```

1. **Pre-payment photo check:** If `status == "needs_photo"`, tell the user why (`no_face` or `multiple_faces`) — nothing was charged.
2. **Human payment step:** Give `checkout_url` to the user so they can complete the $5 Stripe Checkout in their browser.
3. **Poll & unpack:** Poll `GET https://pixel-forge.net/api/jobs/<job_id>` every `5s` (~90–150s total). When `status == "complete"`, download `GET https://pixel-forge.net/api/jobs/<job_id>/download` and unzip into your game's asset folder.

## 3. MCP Server (`@pixel-forge/mcp`)

To register PixelForge as a local stdio MCP server in Cursor, Claude Desktop, Claude Code, or Windsurf without external dependencies (requires Node 18+):

```bash
mkdir -p ~/.pixelforge && curl -fsSL https://pixel-forge.net/static/mcp/pixelforge-mcp.mjs -o ~/.pixelforge/pixelforge-mcp.mjs
```

Add to `.cursor/mcp.json` or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pixelforge": {
      "command": "node",
      "args": ["/Users/YOUR_USER/.pixelforge/pixelforge-mcp.mjs"]
    }
  }
}
```

Exposed MCP tools:
- `download_free_starter_pack(dest_dir)` — downloads & extracts `/samples/starter-pack.zip`
- `create_sprite_job(photo_path, notes?, email?)` — uploads photo & returns Stripe `checkout_url` + `job_id`
- `get_sprite_job_status(job_id)` — checks queue/processing/complete state
- `download_completed_pack(job_id, dest_dir)` — downloads & extracts finished `sprite-package.zip`

## 4. Deterministic Pack Invariants (`manifest.json` v2)

- **Sheets:** `processed/sprite-sheet-96-transparent.png` (`384×384`, `96×96` cells) & `processed/sprite-sheet-48-transparent.png` (`192×192`, `48×48` cells).
- **Row order (0..3):** `down`, `left`, `right`, `up`.
- **Column order (0..3):** `neutral`, `left_step`, `neutral`, `right_step` (`idle_column = 0`).
- **Timing & filtering:** `135 ms/frame` (`7.41 FPS`, or `8 FPS`). **Always** enforce nearest-neighbor / point filtering (`pixelArt: true` in Phaser, `Default Texture Filter = Nearest` in Godot 4, `Filter Mode = Point` + `Compression = None` in Unity 6, `image-rendering: pixelated` in CSS/Canvas).
- **Foot baseline & collider:** `foot_baseline_y = 90` (`96px`) / `45` (`48px`); `recommended_hitbox = {x:24, y:44, w:48, h:46}` (`96px`).
- **Engine sidecars included:**
  - RPG Maker MV/MZ: `processed/rpgmaker/$character.png` (`144×192`, `3×4` cols `[left_step, neutral, right_step]`, idle col `1`).
  - Phaser 3 JSON Hash: `processed/phaser/atlas_96.json` & `processed/phaser/atlas_48.json`.
