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

File	Description
api-reference.md	Full API endpoints, models, prompt_style values, response shape, pricing, and error codes

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:

bash

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:

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

Buy credits (smallest pack is fine for prototyping)

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)

bash

# 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)

bash

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)

bash

# 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

bash

# 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.

bash

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

bash

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

Model Selection Guide

Model	Cost	Sizes	Best for
RD_FAST	$0.015–0.04	64×64 to 384×384	Bulk prototyping, simple sprites, items
RD_PLUS	$0.025–0.08	16×16 to 192×192	Tilesets, top-down, watercolor, Minecraft-style
RD_PRO	$0.18 flat	64×64 to 256×256	Hero sprites, isometric scenes, polish pass (17+ styles, supports up to 9 reference images)
RD_MINI	varies	very small	Routes to PLUS/FAST for tiny pickups

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:

Goal	Prompt	Why
Game character	"a cute green slime, big eyes, side view"	Single subject, perspective named
Item	"a glowing red potion bottle"	Specific shape + color
Tile	"lush grass texture, top down, seamless"	Perspective + tiling intent
Enemy	"a skeleton warrior, hunched, side view"	Silhouette cue ("hunched")

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:

Use
--check-cost
first when generating at unfamiliar sizes or with RD_PRO.
Default to RD_FAST + 64×64 for prototypes. Only upgrade specific hero sprites.
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.
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.
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

Problem	Cause	Fix
`RETRODIFFUSION_API_KEY` not set	Key missing	Ask the user for their key (https://www.retrodiffusion.ai → Account → API). Save to `.env` .
HTTP 401 Unauthorized	Wrong header or invalid key	Header must be `X-RD-Token: <key>` , NOT `Authorization: Bearer` . Verify the key on the dashboard.
HTTP 400 "insufficient credits"	Account balance is empty	Tell the user to top up at the dashboard before retrying. Run `--mode balance` to confirm.
Sprite looks blurry in Phaser	Browser is smooth-scaling the PNG	Set `pixelArt: true` and `roundPixels: true` in the Phaser config.
Output ignores prompt details	Prompt is being auto-expanded into something different	Try `--bypass-prompt-expansion` to send the prompt verbatim.
Tileset edges don't match	Style isn't a wang/tile style	Use `--style wang-tile` for auto-tiling sets, or `--tile-x --tile-y` for seamless single textures.
img2img output ignores reference	Strength too high	Lower `--strength` to 0.4–0.6. Strength 0 keeps the input; strength 1 ignores it.
Inconsistent style across batch	Different seeds and slight prompt variation	Pin `--seed` and reuse the exact same prompt structure for sibling sprites (same character family).

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

retrodiffusion

NPX Install

Tags

SKILL.md Content

Retro Diffusion — True Pixel Art Generation

Reference Files

When to Use

Authentication

CLI Script —
`scripts/retrodiffusion-generate.mjs`

Generate (text-to-pixel-art)

Image-to-Image (refine a reference)

Animations (walk cycles, idles, attacks)

Tilesets

Edit (progressive refinement)

Balance check

Model Selection Guide

Prompt Engineering for Pixel Art

Integration with Phaser Games

Spritesheet Slicing

Cost Discipline

Output Convention

Troubleshooting

Checklist