Sprite Compiler Overview

The Sprite Compiler converts PNG images into PixelRoot32 sprite data arrays. It is available in two modes:

Mode	Interface	Best for
Tool Suite module	Native ImGui GUI (3-panel: Settings / Preview / Log)	Interactive editing, project management, visual preview
Standalone CLI	python main.py from the open-source repo	CI scripts, batch processing, build automation

Both modes produce identical C header output. The Tool Suite module delegates the actual compilation to the pr32-sprite-compiler CLI binary (bundled with the Tool Suite installation or available on PATH). The standalone CLI runs directly from a Python checkout — no Tool Suite required.

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.

Tool Suite GUI

The Tool Suite module provides a 3-panel docked interface:

1. Settings (left): Input image, Tile Size grid, Sprite Selection, Export mode/prefix/output
2. Preview (center): Real-time visual preview of the selected sprite
3. Log (bottom): Colour-coded log entries (Info / Warning / Error / Success)

The module manages .pr32sprite project files so you can save and resume work. Export invokes the external pr32-sprite-compiler CLI automatically — it must be available alongside the Tool Suite or on PATH.

Standalone CLI

The open-source Python repo (PixelRoot32-Sprite-Sheet-Compiler) provides the CLI entry python main.py. 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 (Tool Suite)

The Tool Suite module follows a step-by-step 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. Log: Technical feedback and status messages.

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

The 16-pixel width cap applies only to 1bpp sprites — it is a 1bpp row-format constraint of the engine's Sprite/MultiSprite renderer. Sprite2bpp/Sprite4bpp use a uint8_t width field with no 16-pixel limit.

For 1bpp sprites:

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

For 2bpp sprites:

• Width: any (no fixed cap)
• Colors: Up to 4 colors

For 4bpp sprites:

• Width: any (no fixed cap)
• 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 (Standalone CLI)

All examples below use the standalone CLI (python main.py from the open-source repo PixelRoot32-Sprite-Sheet-Compiler). For the Tool Suite module, open the Sprite Compiler from the Tool Suite launcher and use the 3-panel GUI instead.

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 (Standalone CLI)

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 … (standalone CLI) or use the Tool Suite module GUI
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 max for 1bpp sprites (row-format constraint; 2bpp/4bpp have no fixed cap).
• 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