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

# alias

Extract repeated patterns into single-letter aliases (outputs JSON).

## Usage

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

## Arguments

| Argument | Description |
|----------|-------------|
| `<INPUT>` | Input file containing sprite definitions |

## Options

| Option | Description |
|--------|-------------|
| `--sprite <SPRITE>` | Sprite name (if file contains multiple) |

## Description

The `alias` command analyzes a sprite's grid and identifies repeated patterns that could be replaced with single-letter aliases. This is useful for:
- Reducing file size
- Improving readability of complex sprites
- Identifying reusable patterns

The output is JSON, making it easy to integrate with other tools or scripts.

## Examples

### Basic usage

```bash
# Analyze a sprite for aliasing opportunities
pxl alias sprite.pxl

# Analyze a specific sprite
pxl alias sprites.pxl --sprite hero
```

### Processing output

```bash
# Pretty-print the JSON output
pxl alias sprite.pxl | jq .

# Extract just the suggested aliases
pxl alias sprite.pxl | jq '.aliases'

# Count potential savings
pxl alias sprite.pxl | jq '.savings_percent'
```

## Sample Output

```json
{
  "sprite": "hero",
  "original_tokens": 256,
  "unique_tokens": 8,
  "aliases": [
    {
      "pattern": "black",
      "alias": "b",
      "occurrences": 45
    },
    {
      "pattern": "skin",
      "alias": "s",
      "occurrences": 38
    },
    {
      "pattern": "outline",
      "alias": "o",
      "occurrences": 24
    }
  ],
  "savings_bytes": 312,
  "savings_percent": 28.5
}
```

## How Aliases Work

In Pixelsrc format, you can define aliases in the palette:

```
palette:
  name: hero_colors
  colors:
    black: #000000
    skin: #E0A070
  aliases:
    b: black
    s: skin
```

Then use the short form in grids:

```
grid:
  _ _ b b b b _ _
  _ b s s s s b _
  b s s s s s s b
```

The `alias` command helps identify which aliases would be most beneficial.

## Use Cases

- **Optimization**: Reduce file size for large sprites
- **Refactoring**: Identify patterns before cleaning up sprites
- **Analysis**: Understand token distribution in sprites
- **AI integration**: Pre-process AI output for consistency

## See Also

- [fmt](fmt.md) - Format files after applying aliases
- [inline](inline.md) - View expanded grid
- [explain](explain.md) - Detailed sprite analysis