Skip to content

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 auto-detection.

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: Perfect for build scripts and automation.

✅ Sprite Sheets

Automatically split sprite sheets into individual sprites: 

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

GUI Interface

The GUI is designed to be intuitive and follows a 5-step process:

  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: Quick access to 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

1. Single Sprite Conversion

Convert a single image to a sprite: 

pr32-sprite-compiler player.png player_sprite.h --name PLAYER_SPRITE

2. Animation Frames

Convert multiple frames for animation: 

pr32-sprite-compiler --batch walk_*.png --output-dir animations/ --prefix WALK_

3. Sprite Sheet Processing

Split a sprite sheet into individual sprites: 

pr32-sprite-compiler characters.png output.h --sheet 16x16 --count 8

4. Batch Asset Processing

Process entire asset directories: 

pr32-sprite-compiler --batch assets/sprites/*.png --output-dir src/sprites/

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

# Compile all sprites
pr32-sprite-compiler assets/sprites/*.png --output-dir src/sprites/

# Continue with your build process
platformio run

Advantages Over Manual Creation

✅ Time Saving

  • No manual bit pattern conversion
  • Automatic format optimization
  • Batch processing multiple sprites

✅ Accuracy

  • Correct bit ordering
  • Proper array formatting
  • Valid C++ syntax

✅ Consistency

  • Uniform naming conventions
  • Standardized output format
  • Consistent code structure

✅ Maintainability

  • Easy to regenerate from source images
  • Version control friendly
  • Clear separation of assets and code

Limitations

  • Width limit: 16 pixels for 1bpp (hardware constraint)
  • Color depth: Limited by format (1bpp = 2 colors, 2bpp = 4 colors, etc.)
  • File format: Primarily PNG (other formats may require conversion)

Next Steps

See Also