Available Tools¶

This guide documents tools available to facilitate PixelRoot32 game development.

Sprite Compiler (pr32-sprite-compiler)¶

The Sprite Compiler converts PNG images to PixelRoot32 sprite data formats, making it easy to create sprites from image files.

Basic Usage¶

Command Line:

pr32-sprite-compiler input.png output.h

With Options:

pr32-sprite-compiler input.png output.h --format 1bpp --name MY_SPRITE

Supported Formats¶

1bpp (default): Monochrome, most memory-efficient
2bpp: 4 colors per sprite (requires PIXELROOT32_ENABLE_2BPP_SPRITES)
4bpp: 16 colors per sprite (requires PIXELROOT32_ENABLE_4BPP_SPRITES)

Output Format¶

The compiler generates C++ header files with sprite data:

// output.h
#ifndef SPRITE_DATA_H
#define SPRITE_DATA_H

#include <stdint.h>

static const uint16_t MY_SPRITE_DATA[] = {
    0b00111100,
    0b01111110,
    0b11111111,
    // ... more rows
};

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

#endif

Advanced Options¶

Batch Processing:

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

Custom Palette:

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

Sprite Sheet:

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

GUI Version¶

If available, a GUI version provides visual feedback:

Drag and drop images
Preview sprite data
Adjust settings visually
Export to header files

Step-by-Step Example¶

Create or find a PNG image (8x8, 16x16, etc.)
Run the compiler:

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

Include in your project:

#include "player_sprite.h"

void draw() {
    renderer.drawSprite(PLAYER_SPRITE, 100, 100, Color::White);
}

Troubleshooting¶

Image too large:

Sprites must be ≤ 16 pixels wide for 1bpp
Reduce image size or split into multiple sprites

Colors not converting correctly:

Ensure image uses indexed colors
Use black/white for 1bpp
Use 4 colors for 2bpp, 16 for 4bpp

Output file not found:

Check write permissions
Verify output path exists

Future Tools¶

Music Compiler (Planned)¶

A tool to convert music files or MIDI to PixelRoot32 MusicTrack format.

Planned Features:

MIDI to MusicTrack conversion
Visual music editor
Instrument preset management
Export to C++ header files

Tilemap Compiler (Planned)¶

A tool to create tilemaps from image files or tile editors.

Planned Features:

Image to tilemap conversion
Tile editor integration
Export to C++ arrays
Collision data generation

Other Planned Tools¶

Save System Generator: Generate save/load code
Asset Packer: Bundle assets for distribution
Performance Profiler: Analyze game performance

Using Tools in Development¶

Workflow Integration¶

Typical Workflow:

Create/edit sprites in image editor
Compile sprites to C++ headers
Include headers in project
Use sprites in code

Automation:

# Build script example
#!/bin/bash
pr32-sprite-compiler assets/sprites/*.png --output-dir src/sprites/
# Continue with build...

Best Practices¶

Organize assets: Keep source images separate from generated code
Version control: Commit generated headers, not source images (or both)
Naming conventions: Use consistent naming for sprites
Batch processing: Process multiple sprites at once when possible