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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

# PNG Export

PNG is the default output format for Pixelsrc. Each sprite renders to a transparent PNG file with optional scaling.

## Basic Usage

Render a single sprite to PNG:

```bash
pxl render sprite.pxl
```

This creates `sprite_<name>.png` for each sprite in the file.

## Output Options

### Specifying Output Path

```bash
# Single file output
pxl render sprite.pxl -o hero.png

# Output to directory (must end with /)
pxl render sprite.pxl -o output/

# Specific sprite only
pxl render sprite.pxl --sprite hero -o hero.png
```

### Scaling

Scale output by integer factors (1-16):

```bash
# 2x scale (each pixel becomes 2x2)
pxl render sprite.pxl --scale 2

# 4x scale for high-res preview
pxl render sprite.pxl --scale 4 -o preview.png
```

Scaling uses nearest-neighbor interpolation to preserve pixel art crispness.

## Output Naming

Without `-o`, output follows this pattern:

| Input | Sprites | Output |
|-------|---------|--------|
| `hero.pxl` | 1 sprite | `hero_<sprite_name>.png` |
| `hero.pxl` | Multiple | `hero_<sprite_name>.png` per sprite |
| `hero.jsonl` | 1 sprite | `hero_<sprite_name>.png` |

## Composition Rendering

Render compositions (layered sprites):

```bash
# Render all compositions
pxl render scene.pxl

# Render specific composition
pxl render scene.pxl --composition battle_scene
```

Compositions flatten all layers into a single PNG, respecting:
- Layer order (first layer = background)
- Layer positions (x, y offsets)
- Transparency blending

## Error Handling

### Lenient Mode (Default)

By default, Pixelsrc is lenient:
- Unknown tokens render as magenta (`#FF00FF`)
- Row length mismatches are padded/truncated
- Warnings are printed but rendering continues

```bash
# Normal render (lenient)
pxl render sprite.pxl
# Warning: Unknown token {foo} in sprite "hero"
# Rendered hero.png (with magenta pixels for unknown tokens)
```

### Strict Mode

For CI/CD validation, use strict mode:

```bash
pxl render sprite.pxl --strict
# Error: Unknown token {foo} in sprite "hero"
# Exit code: 1
```

## File Format Details

PNG files are saved with:
- RGBA color (32-bit with alpha channel)
- True transparency (alpha = 0 for `{_}` tokens)
- No compression artifacts (lossless)
- No embedded metadata

## Examples

### Basic Sprite Export

<!-- DEMOS exports/png#basic -->
**Basic PNG Export**

Render a simple sprite to PNG with transparency.

<div class="demo-source">

```jsonl
{"type": "palette", "name": "coin", "colors": {"{_}": "#00000000", "{y}": "#ffd700", "{o}": "#daa520"}}
{"type": "sprite", "name": "coin", "palette": "coin", "grid": ["{_}{y}{y}{_}", "{y}{o}{o}{y}", "{y}{o}{o}{y}", "{_}{y}{y}{_}"]}
```

</div>

<div class="demo-container" data-demo="basic">
</div>

```bash
pxl render coin.pxl -o coin.png
```
<!-- /DEMOS -->

### High-Resolution Preview

<!-- DEMOS exports/png#scaled -->
**Scaled PNG Export**

Scale output for high-resolution previews while preserving pixel art crispness.

<div class="demo-source">

```jsonl
{"type": "palette", "name": "gem", "colors": {"{_}": "#00000000", "{b}": "#4169e1", "{l}": "#87ceeb", "{d}": "#191970"}}
{"type": "sprite", "name": "gem", "palette": "gem", "grid": ["{_}{l}{l}{_}", "{b}{l}{l}{b}", "{b}{b}{b}{b}", "{_}{d}{d}{_}"]}
```

</div>

<div class="demo-container" data-demo="scaled">
</div>

```bash
pxl render gem.pxl --scale 4 -o gem_4x.png
```
<!-- /DEMOS -->

### Batch Processing

```bash
# Render all .pxl files in a directory
for f in assets/*.pxl; do
  pxl render "$f" -o output/
done
```

## Related

- [GIF Animation](gif.md) - Export animated sprites
- [Spritesheet](spritesheet.md) - Combine frames into a single image
- [Atlas Formats](atlas.md) - Game engine integration