BitmapFont Creator

A command-line tool to create bitmap fonts for Phaser games.

Features

• Merge multiple character images into a single texture atlas (PNG)
• Support for extracting frames from sprite sheets
• Character padding support to prevent texture bleeding
• Generate Phaser BitmapText compatible XML font files
• Structured JSON output for programmatic processing

Installation

From Source

git clone https://github.com/lchung0/bitmaptext-creator.git
cd bitmaptext-creator
cargo build --release

The compiled binary will be at target/release/bitmapfont-creator.

From Crates.io

cargo install bitmapfont-creator

Usage

Basic Command

bitmapfont-creator --config font-config.json --output ./dist

Command Line Arguments

Configuration File Format

Basic Format

{
  "font_name": "my-font",
  "output_dir": "./output",
  "A": {
    "path": "chars/A.png",
    "padding": 4
  },
  "B": {
    "path": "chars/B.png",
    "padding": 4
  }
}

Extracting Frames from Sprite Sheet

{
  "font_name": "game-font",
  "A": {
    "path": "spritesheet.png",
    "frame": {"x": 0, "y": 0, "w": 32, "h": 32},
    "padding": 4
  },
  "B": {
    "path": "spritesheet.png",
    "frame": {"x": 32, "y": 0, "w": 32, "h": 32},
    "padding": 4
  }
}

Configuration Fields

* Required when using frame

Output Files

The tool generates two files:

• {font-name}.png - Texture atlas containing all characters
• {font-name}.xml - Phaser BitmapText compatible font description file

XML Format

The generated XML file follows the AngelCode BMFont format:

<?xml version="1.0" encoding="UTF-8"?>
<font>
  <info face="my-font" size="32" ... padding="4,4,4,4" .../>
  <common lineHeight="32" base="26" scaleW="128" scaleH="64" .../>
  <pages>
    <page id="0" file="my-font.png"/>
  </pages>
  <chars count="2">
    <char id="65" x="4" y="4" width="24" height="28" xoffset="0" yoffset="0" xadvance="28" page="0" chnl="15"/>
  </chars>
</font>

Character Attributes

Using with Phaser

// Preload
function preload() {
  this.load.bitmapFont('myFont', 'assets/my-font.png', 'assets/my-font.xml');
}

// Create text
function create() {
  const text = this.add.bitmapText(100, 100, 'myFont', 'Hello World');
  text.setFontSize(32);
}

Reading from Stdin

Useful for programmatic invocation:

echo '{"A":{"path":"a.png"},"font_name":"dynamic-font"}' | \
  bitmapfont-creator --stdin --json

JSON Output Format

Use --json flag for structured output:

Success Response

{
  "success": true,
  "atlas_path": "./output/my-font.png",
  "xml_path": "./output/my-font.xml",
  "char_count": 2,
  "atlas_size": {"width": 128, "height": 64},
  "char_map": {
    "A": {
      "x": 4,
      "y": 4,
      "width": 24,
      "height": 28,
      "xoffset": 0,
      "yoffset": 0,
      "xadvance": 28,
      "padding": 4
    }
  }
}

Error Response

{
  "success": false,
  "error_type": "ImageLoad",
  "error_message": "Failed to load image: chars/A.png",
  "suggestion": "Verify image file exists and is a valid PNG format"
}

Error Types

Tech Stack

• Rust - Systems programming language
• image - Image processing
• serde/serde_json - JSON serialization
• clap - Command line argument parsing
• rectangle-pack - Rectangle packing algorithm

License

This project is licensed under the MIT License.