pixelsrc

The first pixel art format designed for GenAI.

pixelsrc is a semantic, human-readable text format for defining pixel art. Unlike traditional editors or hex-based formats, it's designed from the ground up for AI systems to generate reliably.

// coin.pxl - A simple coin sprite
{
  type: "palette",
  name: "coin",
  colors: {
    _: "transparent",
    outline: "#8B6914",
    gold: "#FFD700",
    shine: "#FFFACD",
  },
}

{
  type: "sprite",
  name: "coin",
  size: [8, 8],
  palette: "coin",
  regions: {
    _: "background",
    outline: { stroke: [1, 1, 6, 6], round: 2 },
    gold: { fill: "inside(outline)" },
    shine: { points: [[3, 2], [4, 3]] },
  },
}

Why pixelsrc?

• Semantic regions - Define shapes like rect, circle, fill instead of individual pixels
• Context-efficient - 64x64 sprites take the same space as 8x8 with similar structure
• GenAI-native - Describe intent, the compiler resolves pixels
• JSON5 format - Comments, trailing commas, unquoted keys for readability
• Lenient by default - Fills gaps and continues on small errors; strict mode available for CI

Installation

One-line installer (Linux/macOS)

Requires Python 3.9+ and HTTPS access to GitHub; no Rust compiler is needed.

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/scbrown/pixelsrc/main/install.sh | sh
pxl --version

The installer selects the latest stable release for Linux (glibc) or macOS, on x86_64 or aarch64. It verifies the archive against the release's SHA256SUMS.txt, accepts only a single regular pxl file, then checks the binary's reported version. This trusts the GitHub release publisher and HTTPS; checksums from the same release do not provide an independent signature. Linux binaries must also support your system's glibc version. Other platforms, including musl Linux, can use Cargo or the release downloads below.

The default destination is ~/.local/share/pixelsrc/vVERSION/pxl, linked as ~/.local/bin/pxl. Add ~/.local/bin to PATH if necessary. Existing directories, command links (including dangling links), and an existing pxl on PATH are refused. Use the original package manager for package-managed installations. The script never edits shell profiles, uses sudo, or changes project files.

For a pinned release or an isolated installation, download and inspect the script, then run:

sh install.sh --version 0.3.1 --prefix "$HOME/tools/pxl-0.3.1"
"$HOME/tools/pxl-0.3.1/pxl" --version
sh install.sh --dry-run  # metadata resolution only; no payload check or writes

A custom prefix creates no global command link. To uninstall, remove only the directory created by this installer and, for a default install, its matching ~/.local/bin/pxl symlink. To upgrade without overwriting anything, install into a new custom prefix and select that command explicitly.

Homebrew (macOS/Linux)

brew install scbrown/pixelsrc/pxl

Cargo

cargo install pixelsrc
# or the latest main:
cargo install --git https://github.com/scbrown/pixelsrc

Download binaries

Pre-built binaries for Linux, macOS, and Windows are available on the Releases page.

Quick Start

1. Create a file hero.pxl:

{
  type: "palette",
  name: "hero",
  colors: {
    _: "transparent",
    outline: "#000000",
    skin: "#FFD5B4",
    hair: "#8B4513",
    eye: "#4169E1",
  },
}

{
  type: "sprite",
  name: "hero",
  size: [16, 16],
  palette: "hero",
  regions: {
    _: "background",
    "head-outline": { stroke: [4, 2, 8, 10], round: 2 },
    hair: { fill: "inside(head-outline)", y: [2, 5] },
    skin: { fill: "inside(head-outline)", y: [5, 12], except: ["eye"] },
    eye: { rect: [6, 7, 2, 2], symmetric: "x" },
  },
}

2. Render it:

pxl render hero.pxl -o hero.png

3. Scale it up:

pxl render hero.pxl -o hero.png --scale 8

Features

CLI Tool (pxl)

Command	Description
pxl render <file>	Render .pxl to PNG
pxl render --gif	Export animations to GIF
pxl render --spritesheet	Generate sprite sheets
pxl fmt <files>	Format files for readability
pxl validate <file>	Check for errors
pxl palettes list	List built-in palettes
pxl import <image>	Convert PNG to .pxl

Format Capabilities

• Palettes - Define reusable color schemes with semantic roles
• Sprites - Define images using geometric regions
• Regions - Shapes: rect, stroke, circle, ellipse, polygon, fill
• Modifiers - symmetric, range constraints (x, y), except
• Animations - Frame sequences with timing
• Compositions - Layer sprites into scenes
• State Rules - Visual states without separate sprites

Integrations

• Web Editor - Live editor with real-time preview
• WASM Module - Use in JavaScript/TypeScript
• Obsidian Plugin - Render sprites in your notes

Development

This project uses just as a command runner:

just --list      # Show all available commands
just build       # Build the project
just test        # Run tests
just check       # Run format check, lint, and tests
just render coin # Render an example sprite

Documentation

• Documentation Book - Complete user guide with interactive examples
• Format Specification - Complete format schema
• AI Primer - Guide for AI generation
• Implementation Plan - Roadmap and phase status
• Vision & Philosophy - Design principles
• Contributing - Development guide

Use Cases

• Game development - Generate sprites with AI assistants
• Prototyping - Quick iteration on visual assets
• Version control - Text-based diffs for pixel art
• Education - Learn pixel art through readable definitions

License

MIT - see LICENSE