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.

Installation¶

From Source:

git clone https://github.com/Gperez88/pr32-sprite-compiler.git
cd pr32-sprite-compiler
npm install
npm link  # Optional: install globally

As NPM Package:

npm install -g pr32-sprite-compiler

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: 1. Create/edit sprites in image editor 2. Compile sprites to C++ headers 3. Include headers in project 4. 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