pixelsrc

Crates.io	pixelsrc
lib.rs	pixelsrc
version	0.2.0
created_at	2026-01-21 05:28:17.732265+00
updated_at	2026-01-21 15:38:26.886049+00
description	Pixelsrc - GenAI-native pixel art format and compiler
homepage	https://github.com/scbrown/pixelsrc
repository	https://github.com/scbrown/pixelsrc
max_upload_size
id	2058385
size	5,066,256

Steve Brown (scbrown)

documentation

README

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.

{"type": "palette", "name": "coin", "colors": {"{_}": "#00000000", "{gold}": "#FFD700", "{shine}": "#FFFACD"}}
{"type": "sprite", "name": "coin", "size": [8, 8], "palette": "coin", "grid": [
  "{_}{_}{gold}{gold}{gold}{gold}{_}{_}",
  "{_}{gold}{shine}{shine}{gold}{gold}{gold}{_}",
  "{gold}{shine}{gold}{gold}{gold}{gold}{gold}{gold}",
  "{gold}{gold}{gold}{gold}{gold}{gold}{gold}{gold}",
  "{_}{gold}{gold}{gold}{gold}{gold}{gold}{_}",
  "{_}{_}{gold}{gold}{gold}{gold}{_}{_}"
]}

Why Pixelsrc?

Semantic tokens - Use meaningful names like {skin}, {gold}, {shadow} instead of single characters or hex codes
GenAI-native - No coordinate systems or spatial reasoning; just sequential rows that LLMs can generate reliably
Streaming-first - JSONL format enables real-time parsing as AI generates each line
Lenient by default - Fills gaps and continues on small errors; strict mode available for CI
Human-readable - Git diffs of sprite changes are meaningful and reviewable

Installation

Homebrew (macOS/Linux)

brew install scbrown/tap/pixelsrc

Cargo (from source)

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

Create a file hero.pxl:

{"type": "palette", "name": "hero", "colors": {"{_}": "#00000000", "{skin}": "#FFD5B4", "{hair}": "#8B4513", "{shirt}": "#4169E1"}}
{"type": "sprite", "name": "hero", "size": [8, 8], "palette": "hero", "grid": [
  "{_}{_}{hair}{hair}{hair}{hair}{_}{_}",
  "{_}{hair}{hair}{hair}{hair}{hair}{hair}{_}",
  "{_}{skin}{skin}{skin}{skin}{skin}{skin}{_}",
  "{_}{skin}{skin}{skin}{skin}{skin}{skin}{_}",
  "{_}{_}{shirt}{shirt}{shirt}{shirt}{_}{_}",
  "{_}{shirt}{shirt}{shirt}{shirt}{shirt}{shirt}{_}",
  "{_}{_}{skin}{_}{_}{skin}{_}{_}",
  "{_}{_}{skin}{_}{_}{skin}{_}{_}"
]}

Render it:

pxl render hero.pxl -o hero.png

Scale it up:

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

Features

CLI Tool (`pxl`)

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

Format Capabilities

Palettes - Define reusable color schemes
Sprites - Pixel grids with semantic tokens
Animations - Frame sequences with timing
Compositions - Layer sprites into scenes
Built-in palettes - Gameboy, Dracula, and more

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 JSONL schema
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

Commit count: 537