pixelsrc 0.2.0

Pixelsrc - GenAI-native pixel art format and compiler
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# Pixelsrc

[![CI](https://github.com/scbrown/pixelsrc/actions/workflows/ci.yml/badge.svg)](https://github.com/scbrown/pixelsrc/actions/workflows/ci.yml)
[![Release](https://github.com/scbrown/pixelsrc/actions/workflows/release.yml/badge.svg)](https://github.com/scbrown/pixelsrc/actions/workflows/release.yml)
[![WASM](https://github.com/scbrown/pixelsrc/actions/workflows/wasm.yml/badge.svg)](https://github.com/scbrown/pixelsrc/actions/workflows/wasm.yml)
[![npm](https://img.shields.io/npm/v/@stiwi/pixelsrc-wasm)](https://www.npmjs.com/package/@stiwi/pixelsrc-wasm)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**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.

```jsonl
{"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)

```bash
brew install scbrown/tap/pixelsrc
```

### Cargo (from source)

```bash
cargo install --git https://github.com/scbrown/pixelsrc
```

### Download binaries

Pre-built binaries for Linux, macOS, and Windows are available on the [Releases](https://github.com/scbrown/pixelsrc/releases) page.

## Quick Start

1. Create a file `hero.pxl`:

```jsonl
{"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}{_}{_}"
]}
```

2. Render it:

```bash
pxl render hero.pxl -o hero.png
```

3. Scale it up:

```bash
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](https://scbrown.github.io/pixelsrc/)** - Live editor with real-time preview
- **[WASM Module](https://www.npmjs.com/package/@stiwi/pixelsrc-wasm)** - Use in JavaScript/TypeScript
- **[Obsidian Plugin](obsidian-pixelsrc/)** - Render sprites in your notes

## Development

This project uses [just](https://github.com/casey/just) as a command runner:

```bash
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](https://scbrown.github.io/pixelsrc/book/)** - Complete user guide with interactive examples
- [Format Specification](docs/spec/format.md) - Complete JSONL schema
- [Implementation Plan](docs/plan/README.md) - Roadmap and phase status
- [Vision & Philosophy](docs/VISION.md) - Design principles
- [Contributing](CONTRIBUTING.md) - 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](LICENSE)