PixelRoot32 Sprite Compiler (pr32-sprite-compiler)

A Python tool that provides multiple interfaces to convert PNG sprite sheets into C header files (.h) compatible with the PixelRoot32 engine:

• GUI: Interactive desktop application (recommended for artists)
• CLI: Command-line interface for automation and build pipelines
• Library: Python API for integration into other tools (e.g., PixelRoot32 Suite)

For every defined sprite it generates one or more arrays:

static const uint16_t SPRITE_0_LAYER_0[] = { /* bit data */ };
static const uint16_t SPRITE_0_LAYER_1[] = { /* bit data */ };
/* ... */

For the engine that consumes these headers, see the PixelRoot32 Game Engine repository.

---

Table of Contents

• Requirements
• Installation
• Usage
  • GUI Mode
  • CLI Mode
  • Library/API Mode
• Sprite Definition
• Output Format
• Common Errors
• Building Executables
• License

---

Requirements

• Python 3.8+
• Pillow (installed automatically via pip)
• ttkbootstrap (optional, for GUI mode)

---

Installation

From Source (Development)

git clone https://github.com/pixelroot32/PixelRoot32-Sprite-Compiler.git
cd PixelRoot32-Sprite-Compiler
pip install -e .

# With GUI support
pip install -e ".[gui]"

From GitHub (Users)

# Latest version
pip install git+https://github.com/pixelroot32/PixelRoot32-Sprite-Compiler.git

# Specific version
pip install git+https://github.com/pixelroot32/PixelRoot32-Sprite-Compiler.git@v0.3.0

Verification

python -c "from pr32_sprite_compiler import compile_sprite_sheet; print('OK')"

---

Usage

GUI Mode

Launch the interactive GUI:

pr32-sprite-compiler
# or
python main.py

CLI Mode

pr32-sprite-compiler INPUT.png   --grid WxH   [--prefix PREFIX]   [--offset X,Y]   --sprite gx,gy,gw,gh   [--out output_file.h]   [--mode {layered,2bpp,4bpp}]

Example:

pr32-sprite-compiler `
  assets/player_sprites.png `
  --grid 16x32 `
  --prefix PLAYER `
  --offset 0,10 `
  --sprite 0,0,1,1 `
  --sprite 1,0,1,1 `
  --out sprites_player.h

Library/API Mode

The compiler can be used as a Python library for integration into other tools.

Basic Usage:

from pr32_sprite_compiler import compile_sprite_sheet, SpriteDefinition, CompilationOptions
from PIL import Image

# Load image
img = Image.open("assets/player.png").convert("RGBA")

# Define sprites
sprites = [
    SpriteDefinition(0, 0, 1, 1, 0),  # frame 0
    SpriteDefinition(1, 0, 1, 1, 1),  # frame 1
]

# Configure options
options = CompilationOptions(
    grid_w=16,
    grid_h=16,
    offset_x=0,
    offset_y=0,
    mode="4bpp",
    output_path="src/player_sprites.h",
    name_prefix="PLAYER"
)

# Compile
success = compile_sprite_sheet(img, sprites, options)

Advanced Usage with Error Handling:

from pr32_sprite_compiler import compile_sprite_sheet
from pr32_sprite_compiler.core.logging import configure_logging
from pr32_sprite_compiler.core.exceptions import ValidationError

# Enable detailed logging
configure_logging(level="DEBUG", detailed=True)

# Compile with error handling
try:
    success = compile_sprite_sheet(
        image, sprites, options, 
        raise_on_error=True
    )
except ValidationError as e:
    print(f"Validation error: {e}")

API Functions:

from pr32_sprite_compiler import (
    compile_sprite_sheet,
    get_supported_palettes,
    get_palette_colors
)

# Get available palettes
palettes = get_supported_palettes()
# ['PALETTE_NES', 'PALETTE_GB', 'PALETTE_GBC', 'PALETTE_PICO8', 'PALETTE_PR32']

# Get colors from a palette
colors = get_palette_colors("PALETTE_NES")
# [(0, 0, 0), (255, 241, 232), ...]

---

Sprite Definition

The sprite sheet is divided into a grid of cells. Position and size are specified in grid units:

• gx, gy: Grid position (0,0 is top-left)
• gw, gh: Grid size (width and height in cells)

Example: --sprite 0,0,1,1 defines a single-cell sprite at position (0,0).

Palette	Description	Preview
PR32 (Default)	The standard PixelRoot32 palette
NES	Nintendo Entertainment System style
GB	GameBoy (Greyscale/Green) style
GBC	GameBoy Color style
PICO8	PICO-8 fantasy console style

• layered (default): One 1bpp array per color layer
• 2bpp: Packed array, 2 bits per pixel (up to 3 colors)
• 4bpp: Packed array, 4 bits per pixel (up to 15 colors)

---

Output Format

Generated .h file structure:

// Generated by PixelRoot32 Sprite Compiler
static const uint16_t PLAYER_SPRITE_0_LAYER_0[] = {
    0x0000,
    0x0C30,
    /* ... */
};

Naming: [PREFIX]_SPRITE_<N>_<MODE>

---

Common Errors

Package Not Found

ModuleNotFoundError: No module named 'pr32_sprite_compiler'

Fix: pip install -e .

Image Mode Error

ImageError: La imagen debe estar en modo RGBA

Fix: img = Image.open("sprite.png").convert("RGBA")

Validation Errors

ValidationError: [grid_w] grid_w debe ser positivo

Fix: Ensure all parameters are valid (grid sizes > 0, valid modes)

---

Building Executables

Using PyInstaller:

# Windows
pyinstaller --noconsole --onefile --add-data "pr32_sprite_compiler�ssets;pr32_sprite_compiler�ssets" main.py

# Linux/macOS
pyinstaller --noconsole --onefile --add-data "pr32_sprite_compiler/assets:pr32_sprite_compiler/assets" main.py

Output: dist/main.exe (Windows) or dist/main (Linux/macOS)

---

Project Structure

pr32_sprite_compiler/
├── __init__.py          # Public API
├── core/
│   ├── api.py          # Main API
│   ├── compiler.py     # Compilation engine
│   ├── exporter.py     # Code generation
│   ├── models.py       # Data models
│   ├── exceptions.py   # Custom exceptions
│   └── logging.py      # Logging utilities
├── gui/
│   └── main_window.py  # GUI application
└── services/
    └── __init__.py     # Backwards compatibility

---

License

MIT License - See LICENSE file for details.