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)

Image-to-Image (refine a reference)

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

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

Tilesets

Edit (progressive refinement)

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

Balance check

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.

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

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

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