pixel-tools

A set of CLI tools useful for building pixel art asset pipelines for games, especially developed using Phaser.

Installation

Manually from release archive

1. Download the latest release archive for your platform (Windows, Linux, or macOS) from itch.io or the GitHub releases page.
2. Extract the archive to a folder of your choice.
3. Add the folder containing the binaries to your system's PATH to use them from any directory.

Using npm

This package is also available on npm, making it easy to use in Web game development workflows.

npm install --save-dev pixel-tools

You can then use the tools directly via npx:

npx atlaspack atlas.yaml output/game
npx fontpack fonts.yaml output/
npx tilepack tilemaps/ output/

Or put into a package.json scripts section, to create an actual asset pipeline:

{
  "scripts": {
    "build:assets": "atlaspack assets/atlas.yaml src/assets/game && fontpack assets/fonts.yaml src/assets/fonts"
  }
}

Atlaspack

A CLI tool for creating packed texture atlases from multiple PNG images. It supports individual sprites, nineslice definitions, and spritesheets, also with named animations.

Features

• Packs multiple PNG images into a single optimized texture atlas
• Supports nineslice metadata for UI elements
• Supports extracting sprites from spritesheets PNGs:
  • Individual sprites can be extracted just by specifying sprite width and height
  • Named sprite sequences can be defined with automatic deduplication of frames referenced multiple times
  • Spritesheet definitions can be imported from external YAML files
• Generates JSON .atlas file compatible with the Phaser game engine

Usage

atlaspack <config.yaml> <output-base>

The tool will process the configuration and output:

• <output-base>.png: The packed texture atlas.
• <output-base>.atlas: A JSON descriptor file containing sprite coordinates and nineslice data.

Configuration Example

# Name of the sprite in the atlas.
- name: hero_
  # Source image path relative to the config file
  image: character.png
  # Optional spritesheet definition
  spritesheet:
    # Width and height of each sprite in the sheet
    sprite_width: 48
    sprite_height: 48
    # Optional mapping of sprite indices to names or animation sequences
    sprite_names:
      idle_front: 0
      walk_front: [0, 1, 2, 0, 4, 5]
# Another sprite with 9-slice borders.
- name: frame
  image: gui_9Slices.png
  nineslice:
    x: 8
    y: 8
    w: 32
    h: 32

For a more detailed example, please see the example folder, which contains a complete configuration with source images and expected output.

Fontpack

A CLI tool for creating packed texture atlases and BMFont character description files from pixel art font sheets. It automates glyph extraction, atlas packing, and coordinate mapping.

Features

• Trims empty space around glyphs to minimize atlas size
• Automatically calculates line height and offsets for consistent baseline alignment
• Packs multiple fonts into a single texture atlas
• Generates XML-based .bmfont files, which can loaded directly by Phaser game engine

Usage

fontpack <font-config.yaml> <output-dir>

The tool expects a YAML configuration file and a directory where it can find source PNG images (named after the font's name property). It outputs:

• fonts.png: A packed texture atlas containing all glyphs.
• <font_name>.bmfont: Individual XML descriptor files for each font.

Configuration Example

# Name of the font. In this case awesome.png will be searched in the same
# folder, where this config.yaml is located, and awesome.bmfont will be generated
# in the output directory
- name: awesome
  # Font cell width and height in the source image in pixels
  size: 16
  # Space between lines in pixels. Line height will be calculated automatically
  # as a height of the biggest character plus line_spacing
  line_spacing: 1
  # Space between letters in pixels
  letter_spacing: 1
  # Width of the space character in pixels
  space_width: 4
  # List of characters to include in the font. Positions of the letters
  # in this list should correspond to positions of letters in the source image
  letters:
    - "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    - "abcdefghijklmnopqrstuvwxyz"
    - "0123456789!\"#$%&'()*+,-./:"
# Name of another font to include in the atlas
- name: another
  size: 16
  line_spacing: 1
# ...and so on

For a more detailed example, please see the example folder, which contains both an example font config with source font images, and an output expected to be generated by the tool.

Tilepack

A CLI tool for repacking and optimizing Tiled map files (*.tmx) and their associated tilesets. The tool analyzes tile usage in maps and creates optimized tilesets containing only the tiles that are actually used in the maps.

Features

• Analyzes TMX map files to identify used tiles
• Creates an optimized tileset by removing unused tiles
• Packs all tiles into a single texture atlas
• Preserves tile properties and object layers
• Supports PNG image format for tilesets
• Handles both embedded and external tilesets
• Outputs JSON tilemaps and a sprite atlas that integrates seamlessly with Phaser engine

Usage

tilepack <source-dir> <destination-dir>

This command will:

1. Scan all .tmx files in the source directory and all associated tilesets
2. Generate optimized output in the destination folder:
   • JSON tilemaps (compatible with Phaser engine)
   • tileset.png and tileset.atlas containing all used tiles and sprites

Example input and output structures:

source/
├── level1.tmx
└── level2.tmx

somewhere-referred-from-tmx-files/
├── terrain.tsx
├── terrain.png
├── trees.tsx
└── trees.png

destination/
├── level1.tmj
├── level2.tmj
├── tileset.png
└── tileset.atlas

Recolor

A simple CLI tool for color conversion between images using a color lookup table (LUT). It has two main functions:

1. Building a LUT by analyzing pairs of source and target images to learn color mappings
2. Applying the LUT to convert new images from source to target color style

The tool was originally developed to convert Time Fantasy tilesets to match the SNES-style colors of Time Elements assets (both created by finalbossblues). However, it can be used for any image color conversion where you have example pairs showing the desired color mapping.

A pre-built LUT file is included for Time Fantasy to Time Elements conversion. Please see the example config file for details on all available options.

Terms of use

Code

All tools are free to download and use for any purpose, including commercial projects. Full source code is available on GitHub under MPL 2.0 license, which means you're also free to modify and redistribute these tools - the main restriction is that if (and only if) you're redistributing modified versions, you must also provide source code of your modifications to your customers. See the file LICENSE for the full license text.

Example art assets

Example assets included in this repository were created by Gabriel Lima aka tiopalada, with small modifications by me. Big thanks to him for creating beautiful pixel art and putting it into the public domain. His work is licensed partially under CC0 1.0 Universal, and partially under CC BY 4.0, for details please see LICENSE files in corresponding example folders.