The AI Enthusiast

You want to generate pixel art using AI. Claude, GPT, or other LLMs—you're harnessing AI to create game assets at scale.

Why Pixelsrc for AI?

Pixelsrc was designed with AI generation in mind:

  • Text-based: LLMs excel at generating structured text
  • Semantic tokens: skin is more reliable than hex codes
  • JSON5 format: Human-readable with comments and trailing commas
  • Lenient parsing: Small AI mistakes don't break everything
  • Deterministic output: Same input = same rendered image

Your Workflow

  1. Write or refine a system prompt
  2. Give the AI examples and constraints
  3. Generate sprites iteratively
  4. Validate and render output

Getting Started

Use the Built-in Prompts

Pixelsrc includes optimized system prompts:

pxl prompts show sprite

This displays a prompt tuned for sprite generation. Copy it into your AI conversation.

List Available Prompts

pxl prompts list

Available prompts:

  • sprite - Single sprite generation
  • animation - Animation sequences
  • character - Full character with variants
  • tileset - Tileable environment pieces

Prompting Strategies

Be Specific About Size

Create a 16x16 sprite of a treasure chest.

AI tends to make sprites too large without constraints.

Provide Palette Constraints

Use only these colors:
- _: transparent
- outline: #1a1a2e (dark outline)
- wood: #8b4513 (wood brown)
- metal: #c0c0c0 (metal gray)
- gold: #ffd700 (gold accents)

Limiting the palette improves consistency and reduces errors.

Show Examples

Include a working example in your prompt:

Here's an example of the format:

{
  type: "palette",
  name: "chest",
  colors: {
    _: "transparent",
    wood: "#8B4513",
    metal: "#C0C0C0",
  },
}

{
  type: "sprite",
  name: "chest_closed",
  size: [6, 5],
  palette: "chest",
  regions: {
    metal: { rect: [1, 0, 4, 1], z: 1 },
    wood: {
      union: [
        { rect: [0, 1, 6, 3] },
        { rect: [1, 4, 4, 1] },
      ],
      z: 0,
    },
  },
}

Now create a 12x10 sprite of a key using similar style.

Request Semantic Naming

Use descriptive token names like handle, blade, shine rather than single letters.

This makes AI output more maintainable.

Iteration Workflow

Generate → Validate → Refine

  1. Generate: Ask AI for a sprite
  2. Save: Copy output to sprite.pxl
  3. Validate: pxl validate sprite.pxl
  4. Preview: pxl show sprite.pxl
  5. Refine: Ask AI to fix issues or adjust

Common AI Fixes

If the AI makes mistakes, you can ask for corrections:

The region coordinates are outside the sprite bounds. The sprite is 16x16,
so all coordinates must be within [0,0] to [15,15].
Please regenerate with valid region bounds.

The sprite is using "green" but the palette doesn't define that token.
Add green to the palette or use an existing color.

Lenient Mode for Prototyping

During iteration, lenient mode (the default) is your friend:

pxl show sprite.pxl  # Shows sprite even with minor errors

Missing tokens render as magenta, helping you spot issues visually.

Batch Generation

Character Variants

Ask AI to generate multiple variants:

Generate a base knight sprite, then create variants:
1. knight_idle - Standing pose
2. knight_walk_1, knight_walk_2, knight_walk_3, knight_walk_4 - Walk cycle
3. knight_attack_1, knight_attack_2, knight_attack_3 - Attack sequence

Use the same palette for all sprites.

Asset Packs

Generate cohesive sets:

Create a dungeon tileset with these 16x16 tiles:
1. floor - Stone floor
2. wall_top - Top of wall
3. wall_front - Front-facing wall
4. door_closed - Closed wooden door
5. door_open - Open door
6. torch - Wall torch with flame

Use a consistent dark fantasy palette.

System Prompt Template

Here's a template for reliable AI generation:

You are a pixel art generator that outputs Pixelsrc format (JSON5).

Rules:
1. Output valid JSON5, one object per line or formatted with newlines
2. Define palettes before sprites that use them
3. Use semantic token names: skin, hair, outline (not single letters)
4. Sprites need size: [width, height] and regions with shapes
5. Shapes: rect [x, y, w, h], points [[x,y],...], circle [cx, cy, r], ellipse [cx, cy, rx, ry]
6. _ is the conventional transparent color token

Format example:
{
  type: "palette",
  name: "example",
  colors: {
    _: "transparent",
    main: "#FF0000",
  },
}

{
  type: "sprite",
  name: "example",
  size: [3, 3],
  palette: "example",
  regions: {
    main: {
      union: [
        { points: [[1, 0]] },
        { rect: [0, 1, 3, 1] },
        { points: [[1, 2]] },
      ],
      z: 0,
    },
  },
}

When I request a sprite, respond with ONLY valid Pixelsrc JSON5. No explanations.

Validation in AI Pipelines

Automated Validation

import subprocess
import json

def validate_pixelsrc(content: str) -> tuple[bool, str]:
    """Validate Pixelsrc content, return (success, error_message)."""
    with open("temp.pxl", "w") as f:
        f.write(content)

    result = subprocess.run(
        ["pxl", "validate", "temp.pxl", "--strict", "--json"],
        capture_output=True,
        text=True
    )

    if result.returncode == 0:
        return True, ""
    return False, result.stderr

Retry Loop

def generate_sprite(prompt: str, max_retries: int = 3) -> str:
    for attempt in range(max_retries):
        response = ai_generate(prompt)

        valid, error = validate_pixelsrc(response)
        if valid:
            return response

        # Ask AI to fix the error
        prompt = f"The previous output had this error: {error}\nPlease fix and regenerate."

    raise Exception("Failed to generate valid sprite")

Suggestions and Fixes

Get AI-Friendly Suggestions

pxl suggest sprite.pxl

This outputs suggestions the AI can understand and act on.

Prime Your Conversation

pxl prime sprite.pxl

Generates context about the file that helps AI understand existing work.

Best Practices

Start Simple

Begin with small sprites (8x8, 12x12) before attempting larger ones.

Provide Visual Reference

If possible, describe what you want in detail:

A 16x16 potion bottle:
- Glass bottle shape (rounded bottom, narrow neck)
- Purple liquid filling 2/3 of the bottle
- Cork stopper at top
- Small highlight on glass
- Dark outline around entire sprite

Iterate on Style

Once you get a sprite you like, ask AI to generate more in the same style:

Great! Now create a health potion, mana potion, and speed potion
using the same visual style and palette.

Save Your Prompts

Keep successful prompts in a prompts/ directory for reuse.

Next Steps