Skip to content

Sprite Compiler Overview

The Sprite Compiler (pr32-sprite-compiler) is a command-line tool that converts PNG images into PixelRoot32 sprite data formats. It automates the process of creating sprite arrays from image files, saving you time and ensuring correct format conversion.

What It Does

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

  • Sprite data arrays: Optimized uint16_t arrays for 1bpp sprites
  • Sprite structures: Ready-to-use pixelroot32::graphics::Sprite definitions
  • Multi-sprite support: Handles sprite sheets and animations
  • Format options: Supports 1bpp (standard), 2bpp, and 4bpp formats

Key Features

✅ Format Support

  • 1bpp (Monochrome): Standard format, most memory-efficient
  • 2bpp (4 colors): Experimental, requires build flags
  • 4bpp (16 colors): Experimental, requires build flags
  • MultiSprite: Layer compositions for complex sprites

✅ Batch Processing

Process multiple images at once: 

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

✅ Sprite Sheets

Automatically split sprite sheets into individual sprites: 

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

✅ Custom Palettes

Use custom color palettes for conversion: 

pr32-sprite-compiler input.png output.h --palette custom.json

✅ GUI Version (Optional)

Visual interface for: - Drag and drop image processing - Real-time preview of sprite data - Visual settings adjustment - Export to header files

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:

#ifndef SPRITE_DATA_H
#define SPRITE_DATA_H

#include <stdint.h>
#include <graphics/Sprite.h>

// Sprite data array
static const uint16_t MY_SPRITE_DATA[] = {
    0b00111100,  // Row 0
    0b01111110,  // Row 1
    0b11111111,  // Row 2
    // ... more rows
};

// Sprite structure
static const pixelroot32::graphics::Sprite MY_SPRITE = {
    MY_SPRITE_DATA,  // data pointer
    8,                // width
    8                 // height
};

#endif

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