Sprite Compiler Overview

The Sprite Compiler is a tool that converts PNG images into PixelRoot32 sprite data formats. It provides both a graphical interface (GUI) and a command-line interface (CLI) to automate the process of creating sprite arrays from image files.

What It Does

The Sprite Compiler takes bitmap images (PNG) and converts them into C header files containing:

• Sprite data arrays: Optimized uint16_t arrays for various formats.
• Layered support: Generates multiple 1bpp layers for complex sprites.
• Packed formats: Supports 2bpp and 4bpp packed formats.
• Sprite sheets: Handles grid-based sprite sheets with cell selection.

Key Features

Format support

• Layered (1bpp): Standard format, generates one array per color.
• 2bpp (4 colors): Packed format, 2 bits per pixel.
• 4bpp (16 colors): Packed format, 4 bits per pixel.

GUI & CLI

• Modern GUI: Step-by-step card-based interface for easy configuration.
• Powerful CLI: Suited to build scripts and automation via python main.py.

Sprite sheets

Example: two cells from a sheet using --grid and repeated --sprite:

python main.py sheet.png --grid 16x16 --sprite 0,0,1,1 --sprite 1,0,1,1 --out output.h

GUI Interface

The GUI follows a linear flow:

1. Input Image: Select your PNG source.
2. Grid Settings: Define the cell size and offsets.
3. Sprite Selection: Pick which cells to export.
4. Export Settings: Choose the mode (Layered, 2bpp, 4bpp), set a Prefix, and choose the output path.
5. About: Version info and credits (via the ? button).
6. Log: Technical feedback and performance alerts.

Input Requirements

Supported formats

• PNG: Primary format (recommended)
• Indexed color PNG: Best for 1bpp conversion
• Grayscale PNG: Automatically converted to 1bpp
• RGB PNG: Converted using threshold or palette

Image constraints

For 1bpp sprites:

• Maximum width: 16 pixels
• Height: Any (typically 8, 16, 32 pixels)
• Colors: Black and white (or converted automatically)

For 2bpp sprites:

• Maximum width: 16 pixels
• Colors: Up to 4 colors

For 4bpp sprites:

• Maximum width: 16 pixels
• Colors: Up to 16 colors

Output Format

The compiler generates C header files with optimized arrays:

// Generated by PixelRoot32 Sprite Compiler

// Optional palette mapping if using custom colors
static const Color PLAYER_PALETTE_MAPPING[16] = {
    (Color)0, (Color)1, (Color)2, (Color)3,
    // ...
};

// Sprite data array (4bpp example)
static const uint16_t PLAYER_SPRITE_0_4BPP[] = {
    0x0000, 0x1234, 0x5678, // Row 0
    // ... more rows
};

Use Cases

All examples assume you are in the Sprite Compiler repository directory (or invoke main.py with a full path). The CLI is python main.py.

1. Single sprite conversion

Convert one cell from an image into a header (example: 16×16 grid, one sprite at origin):

python main.py player.png --grid 16x16 --sprite 0,0,1,1 --prefix PLAYER --out player_sprite.h

2. Multiple cells / animation frames

Run once per region (or per file), for example three frames from one sheet:

python main.py sheet.png --grid 16x16 --sprite 0,0,1,1 --sprite 1,0,1,1 --sprite 2,0,1,1 --prefix WALK --out walk_frames.h

Or loop over separate PNGs:

mkdir -p animations
for f in walk_*.png; do
  python main.py "$f" --grid 16x16 --sprite 0,0,1,1 --prefix WALK_ --out "animations/${f%.png}.h"
done

3. Sprite sheet processing

Same pattern: define grid size and one or more --sprite gx,gy,gw,gh regions (see Usage guide).

4. Batch asset processing

Example: every PNG in a folder, same grid, one sprite per file:

mkdir -p src/sprites
for f in assets/sprites/*.png; do
  base=$(basename "$f" .png)
  python main.py "$f" --grid 16x16 --sprite 0,0,1,1 --prefix "${base}_" --out "src/sprites/${base}.h"
done

Workflow integration

Typical development workflow

1. Create sprites in your image editor (Aseprite, Piskel, GIMP, etc.)
2. Save as PNG with appropriate dimensions
3. Run python main.py … to generate header files
4. Include headers in your PixelRoot32 project
5. Use sprites in your game code

Automation example

#!/bin/bash
# build-sprites.sh
set -e
COMPILER_DIR="/path/to/PixelRoot32-Sprite-Compiler"
cd "$COMPILER_DIR"
for f in /path/to/your-game/assets/sprites/*.png; do
  base=$(basename "$f" .png)
  python main.py "$f" --grid 16x16 --sprite 0,0,1,1 --out "/path/to/your-game/src/sprites/${base}.h"
done
cd /path/to/your-game
platformio run

Advantages over manual creation

• Time: No manual bit-pattern conversion; batch-friendly.
• Accuracy: Correct bit ordering and valid C++-style output.
• Consistency: Uniform naming when using --prefix.
• Maintainability: Regenerate from source PNGs; assets stay separate from logic.

Limitations

• Width limit: 16 pixels wide for these sprite modes (engine / hardware constraint).
• Color depth: Limited by format (1bpp = 2 colors, 2bpp = 4, 4bpp = 16).
• File format: Primarily PNG (convert other formats first).

Next steps

• Installation
• Usage guide
• Advanced features

See also

• Rendering — using graphics in-game
• Sprites example — engine sample project
• Sprite (API)
• Tools overview