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:

pxl render sprite.pxl

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

Output Options

Specifying Output Path

# 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):

# 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:

InputSpritesOutput
hero.pxl1 spritehero_<sprite_name>.png
hero.pxlMultiplehero_<sprite_name>.png per sprite
hero.jsonl1 spritehero_<sprite_name>.png

Composition Rendering

Render compositions (layered sprites):

# 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
# 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:

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

Basic PNG Export

Render a simple sprite to PNG with transparency.

{"type": "palette", "name": "coin", "colors": {"_": "#00000000", "y": "#ffd700", "o": "#daa520"}}
{"type": "sprite", "name": "coin", "size": [4, 4], "palette": "coin", "regions": {"y": {"union": [{"rect": [1, 0, 2, 1]}, {"points": [[0, 1], [3, 1], [0, 2], [3, 2]]}, {"rect": [1, 3, 2, 1]}], "z": 0}, "o": {"rect": [1, 1, 2, 2], "z": 1}}}

pxl render coin.pxl -o coin.png

High-Resolution Preview

Scaled PNG Export

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

{"type": "palette", "name": "gem", "colors": {"_": "#00000000", "b": "#4169e1", "l": "#87ceeb", "d": "#191970"}}
{"type": "sprite", "name": "gem", "size": [4, 4], "palette": "gem", "regions": {"l": {"rect": [1, 0, 2, 2], "z": 0}, "b": {"union": [{"points": [[0, 1], [3, 1]]}, {"rect": [0, 2, 4, 1]}], "z": 0}, "d": {"rect": [1, 3, 2, 1], "z": 0}}}

pxl render gem.pxl --scale 4 -o gem_4x.png

Batch Processing

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