Retrodiffusion

Retro Diffusion — True Pixel Art Generation

Generate authentic pixel art sprites, tilesets, and animations from text prompts or reference images using the Retro Diffusion API. Output is true pixel art (clean integer-pixel grids, limited palettes), not blurry diffusion-model output downscaled into pixels — making it the best AI option for shippable 2D game art and fast prototyping.

Paid service. Retro Diffusion requires an account at https://www.retrodiffusion.ai and an API key with credits. Always tell the user this requires a paid Retro Diffusion account before generating anything, and confirm they understand each call deducts from their balance.

Reference Files

When to Use

• Quick prototypes — generate dozens of unique sprites in a minute instead of hand-coding 16×16 arrays
• Polish pass on a working game — replace placeholder shapes with cohesive pixel art that already matches a chosen style
• Tilesets — wang-style ground/wall sets without manually drawing every transition tile
• Sprite animations — walk cycles, idle bobs, attacks delivered as transparent GIFs or spritesheets

Choose this over `add-assets` (code-only pixel art) when: the user wants AI-generated art, has a Retro Diffusion key, or the game needs more visual variety than hand-coded matrices can deliver in a reasonable time. The two skills compose well — Retro Diffusion for hero sprites/tilesets, code-only matrices as a free fallback for quick filler.

Do NOT use this for: 3D models (use meshyai), 3D worlds (use worldlabs), audio (use game-audio), or when the user explicitly wants the all-code procedural pixel art approach (use add-assets).

Authentication

Before prompting the user, check if the key already exists:

test -f .env && grep -q '^RETRODIFFUSION_API_KEY=.' .env && echo "found"

If found, export it with set -a; . .env; set +a and skip the prompt.

If the key is not set, ask the user immediately and explain the cost model:

I'll generate true pixel art with Retro Diffusion — the best dedicated pixel art model for shippable game sprites.

>

Heads up: this is a paid service. You'll need a Retro Diffusion account with credits. Each image typically costs between $0.015 (RD_FAST) and $0.18 (RD_PRO). Get a key in 60 seconds:

>

1. Sign up at https://www.retrodiffusion.ai

2. Buy credits (smallest pack is fine for prototyping)

3. Account → API → Generate API key

>

Paste your key like: RETRODIFFUSION_API_KEY=rdpk-...

(It will be saved to .env and redacted from this conversation.)

>

Or type "skip" to fall back to free hand-coded pixel art via /add-assets.

If the user provides a key, save it to .env and use it via set -a; . .env; set +a && node scripts/retrodiffusion-generate.mjs ....

If the user skips, stop and hand off to `/add-assets` — do not silently degrade to a different art style without telling them.

CLI Script — scripts/retrodiffusion-generate.mjs

Zero-dependency Node.js script. Handles all six modes: generate, img2img, animate, tileset, edit, and balance.

Generate (text-to-pixel-art)

# Single 64×64 sprite, RD_FAST (cheapest)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate \
  --prompt "a cute green slime with big eyes" \
  --model RD_FAST --style retro \
  --width 64 --height 64 \
  --output public/assets/sprites/ --slug slime

# Higher quality with RD_PRO (flat $0.18, supports up to 256×256)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate \
  --prompt "a heroic knight, full body, side view" \
  --model RD_PRO --style fantasy \
  --width 128 --height 128 \
  --output public/assets/sprites/ --slug knight

# Transparent background for game sprites
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "a treasure chest, closed" \
  --model RD_FAST --style game-asset \
  --width 64 --height 64 --remove-bg \
  --output public/assets/sprites/ --slug chest

# Seamless tiling texture (e.g., grass, water)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "lush grass texture, top down" \
  --model RD_PLUS --style top-down \
  --width 64 --height 64 --tile-x --tile-y \
  --output public/assets/tiles/ --slug grass

# Estimate cost before paying for it
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "..." --check-cost

Image-to-Image (refine a reference)

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode img2img \
  --image ./concept-art/hero-sketch.png \
  --prompt "a heroic knight in shining armor" \
  --model RD_FAST --style retro \
  --width 64 --height 64 --strength 0.75 \
  --output public/assets/sprites/ --slug hero

--strength controls how much the AI deviates from the input (0 = identical, 1 = ignore input). 0.5–0.8 is the useful range.

Animations (walk cycles, idles, attacks)

# Walk cycle — returns spritesheet PNG or transparent GIF (style-dependent)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode animate \
  --prompt "a knight walking" \
  --model RD_PRO --style walk-cycle \
  --width 64 --height 64 \
  --output public/assets/sprites/ --slug knight-walk

# Idle bob from an existing character
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode animate --image public/assets/sprites/knight.png \
  --prompt "knight idle breathing" --style idle \
  --output public/assets/sprites/ --slug knight-idle

Animation styles cost $0.07–$0.25 depending on type. See api-reference.md for the full style list.

Tilesets

# Wang-style tileset (auto-tiling ground/wall sets)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode tileset \
  --prompt "stone dungeon floor, mossy" \
  --model RD_PLUS --style wang-tile \
  --width 96 --height 96 \
  --output public/assets/tiles/ --slug dungeon-floor

# Single detailed tile
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode tileset --prompt "wooden bridge plank" --style single-tile \
  --width 64 --height 64 --output public/assets/tiles/ --slug bridge

Edit (progressive refinement)

Flat $0.06 per edit. Use to tweak a generated sprite without re-rolling from scratch.

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode edit --image public/assets/sprites/knight.png \
  --prompt "give the knight a red cape" \
  --output public/assets/sprites/ --slug knight-red

Balance check

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs --mode balance

Model Selection Guide

Default to RD_FAST for prototyping. Upgrade individual hero sprites to RD_PRO when the prototype is shipping.

See api-reference.md for the complete per-model prompt_style list.

Prompt Engineering for Pixel Art

Good prompts are short, specific about silhouette and palette, and call out the perspective:

Avoid:

• Multiple subjects in one prompt — generate separately and composite in-game
• Abstract concepts ("the feeling of dread") — describe the visual instead
• Mismatched perspective ("top-down knight, side view") — pick one

Integration with Phaser Games

Retro Diffusion outputs are normal PNGs — they slot directly into Phaser's loader.

// In a preload scene:
this.load.image('slime', 'assets/sprites/slime.png');
this.load.spritesheet('knight-walk', 'assets/sprites/knight-walk.png', {
  frameWidth: 64,
  frameHeight: 64,
});

// In create():
const slime = this.physics.add.sprite(100, 100, 'slime');
this.anims.create({
  key: 'knight-walk',
  frames: this.anims.generateFrameNumbers('knight-walk', { start: 0, end: 7 }),
  frameRate: 12,
  repeat: -1,
});

Pixel-perfect rendering — when using AI pixel art, configure the Phaser game with crisp scaling so sprites stay sharp:

// In main.js, Phaser config:
const config = {
  type: Phaser.AUTO,
  pixelArt: true,           // disables antialiasing, preserves hard pixel edges
  roundPixels: true,        // snaps sprite positions to integers
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
  // ...
};

Without pixelArt: true, the browser will smooth-scale the PNGs and the pixel-art look is lost.

Spritesheet Slicing

Animation styles return either a transparent GIF or a horizontal spritesheet (style-dependent — check the output PNG dimensions). For spritesheets, infer frameWidth = imageWidth / frameCount and load with this.load.spritesheet(). The .meta.json file written next to each output records the requested width/height so frame count is recoverable.

Cost Discipline

Every call costs real money from the user's balance. Apply these defaults to avoid waste:

1. Use `--check-cost` first when generating at unfamiliar sizes or with RD_PRO. 2. Default to RD_FAST + 64×64 for prototypes. Only upgrade specific hero sprites. 3. Use `--seed` when iterating on a prompt — same seed + same prompt = same image, so you can A/B test prompt edits without re-rolling random variations. 4. Cache outputs — generated PNGs are committed to public/assets/sprites/. Never regenerate an asset that already exists unless the user asked for a new variant. 5. Run `--mode balance` before a big batch so the user sees their remaining credits.

Output Convention

public/assets/sprites/
  slime.png            # generated image
  slime.meta.json      # prompt, model, style, cost, balance, timestamps
  knight-walk.png      # animation spritesheet or GIF
  knight-walk.meta.json
public/assets/tiles/
  grass.png            # tiling texture
  grass.meta.json

Always write a .meta.json next to each PNG so the prompt and seed are recoverable for later regeneration.

Troubleshooting

Checklist

• [ ] User informed this is a paid service — Retro Diffusion account + credits required
• [ ] RETRODIFFUSION_API_KEY checked in .env or env, prompted if missing
• [ ] Model + style chosen for the budget (RD_FAST for prototyping, RD_PRO for hero sprites)
• [ ] --check-cost used for the first call at any new size
• [ ] Prompt is specific about subject, perspective, and silhouette
• [ ] --seed pinned when generating siblings (e.g., walk + idle of the same character)
• [ ] --remove-bg used for game sprites (transparent PNG)
• [ ] --tile-x/--tile-y used for textures, --style wang-tile for auto-tiling
• [ ] PNG written to public/assets/sprites/ (or tiles/) with .meta.json alongside
• [ ] Phaser config has pixelArt: true and roundPixels: true
• [ ] Spritesheet frameWidth/frameHeight matches the requested width/height
• [ ] User shown remaining balance after the batch

Retro Diffusion API Reference

Companion file for SKILL.md. Full API endpoint specifications based on the official examples repo: https://github.com/Retro-Diffusion/api-examples.

Base URL

https://api.retrodiffusion.ai/v1

Authentication

All requests require this header:

X-RD-Token: <your-api-key>

Keys come from the Retro Diffusion dashboard (https://www.retrodiffusion.ai → Account → API). Keys typically start with rdpk-.

Wrong format: the API does not use Authorization: Bearer <key>. Using the wrong header returns HTTP 401.

Endpoints

POST /inferences — Generate Image

Request body

{
  "prompt": "a cute green slime",
  "negative_prompt": "blurry, photorealistic",
  "model": "RD_FAST",
  "prompt_style": "retro",
  "width": 64,
  "height": 64,
  "num_images": 1,
  "seed": 12345,
  "input_image": "<base64 PNG, optional>",
  "input_palette": "<base64 PNG, optional>",
  "strength": 0.75,
  "remove_bg": false,
  "tile_x": false,
  "tile_y": false,
  "bypass_prompt_expansion": false,
  "check_cost": false,
  "include_downloadable_data": false
}

Response (success)

{
  "created_at": 1733425519,
  "model": "rd_fast",
  "balance_cost": 0.025,
  "remaining_balance": 100.75,
  "base64_images": ["iVBORw0KGgo..."],
  "downloadable_data": null
}

Response (error)

{ "error": "Insufficient credits" }

POST /edit — Edit an Image

Flat $0.06 per call. Lighter-weight than re-rolling a full inference.

Request body

{
  "prompt": "give the knight a red cape",
  "input_image": "<base64 PNG>"
}

Response

Same shape as /inferences — base64_images[0] contains the edited PNG.

GET /inferences/credits — Check Balance

No body. Response:

{ "credits": 24.50 }

(Field name may also appear as remaining_balance depending on plan tier.)

Model Sizes

Out-of-range dimensions return HTTP 400. Always check the per-model limits before sending.

Style Catalog

Each model exposes its own prompt_style keys. Common values seen in the official examples:

RD_PRO (17+ styles)

default, painterly, fantasy, ui-panel, horror, sci-fi, isometric, platformer, dungeon-map, character-turnaround, walk-cycle, idle, attack, inventory-sheet, portrait, concept, creature

RD_FAST (15 styles)

default, retro, arcade, simple, detailed, anime, texture, ui, game-asset, character, portrait, prop, effect, weapon, enemy

RD_PLUS (18+ styles)

default, watercolor, top-down, cartoon, isometric-asset, minecraft, low-res-16, low-res-32, low-res-64, wang-tile, single-tile, terrain, building, plant, creature, weapon, effect, ui

RD_MINI

Routes — pass any RD_PLUS or RD_FAST style key.

The exact set of keys is updated by Retro Diffusion server-side. If a style returns 400 ("invalid style"), check the dashboard or the official examples repo for the current list. The names above are stable enough for prototyping.

Pricing (as of 2026)

Multiply by num_images for batch calls. Use check_cost: true on /inferences to preview before paying.

Custom Styles (POST /styles)

Custom styles are RD_PRO-based. Useful for locking a consistent look across a whole game.

Request body

{
  "name": "my-game-style",
  "description": "Muted NES palette, side-view characters",
  "reference_images": ["<base64 PNG>", "..."],
  "llm_instructions": "Always render in NES-style limited palette, side-view, ...",
  "forced_dimensions": { "width": 96, "height": 96 }
}

forced_dimensions is optional and accepts widths/heights between 96 and 256.

Response

{ "id": "style-abc123", "name": "my-game-style", "created_at": 1733425519 }

Use the returned id as prompt_style on subsequent /inferences calls.

Source

Official examples repo (recommended reading before integrating):

• https://github.com/Retro-Diffusion/api-examples
• img2img.py — minimal Python example with full request/response handling