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

# explain

Explain sprites and other objects in human-readable format.

## Usage

```
pxl explain [OPTIONS] <INPUT>
```

## Arguments

| Argument | Description |
|----------|-------------|
| `<INPUT>` | Input file containing Pixelsrc objects |

## Options

| Option | Description |
|--------|-------------|
| `-n, --name <NAME>` | Name of specific object to explain (sprite, palette, etc.) |
| `--json` | Output as JSON |

## Description

The `explain` command provides detailed, human-readable descriptions of Pixelsrc objects including:
- Dimensions and size information
- Color usage statistics
- Animation frame counts
- Composition structure
- And more

This is useful for understanding complex sprites or debugging issues.

## Examples

### Explain all objects

```bash
# Explain everything in a file
pxl explain character.pxl
```

### Explain specific object

```bash
# Explain just the hero sprite
pxl explain character.pxl --name hero

# Explain a palette
pxl explain character.pxl --name colors
```

### JSON output

```bash
# Get structured output
pxl explain character.pxl --json

# Filter with jq
pxl explain character.pxl --json | jq '.sprites[0].dimensions'
```

## Sample Output

```
Sprite: hero
  Dimensions: 16x16 pixels
  Colors used: 5
    - skin (tan): 42 pixels
    - outline (black): 28 pixels
    - hair (brown): 18 pixels
    - shirt (blue): 32 pixels
    - transparent: 136 pixels

Palette: colors
  Colors: 8 defined
    skin    #E0A070
    outline #000000
    hair    #8B4513
    shirt   #4169E1
    ...

Animation: walk
  Frames: 4
  Duration: 400ms total (100ms per frame)
  Sprites: hero_walk_1, hero_walk_2, hero_walk_3, hero_walk_4
```

## Use Cases

- **Debugging**: Understand why a sprite looks wrong
- **Documentation**: Generate sprite documentation automatically
- **Analysis**: Count colors, measure dimensions, audit animations
- **Learning**: Understand how existing sprites are structured

## See Also

- [analyze](analyze.md) - Extract metrics from multiple files
- [show](show.md) - Visual preview in terminal
- [diff](diff.md) - Compare two sprites