TUTORIAL.md

# 🎨 PXG-Tiny — 5-Minute Tutorial

Turn plain English into 16×16 pixel-art sprites, fully offline.
*By Chowdhury Tarul Ahsan — tarulahsan@gmail.com*

---

## 1. Install (30 seconds)

```bash
# Python 3.9+ — only two libraries, no torch, no GPU
pip install numpy pillow
```

Unzip the release anywhere. You get this layout:

```
pxg-tiny/
├── cli.py              ← command-line app
├── weights/            ← the trained model (~1 MB)
├── src/pxg_tiny/       ← inference library (pure NumPy)
├── samples/gallery/    ← sprites made by the final model
└── tests/              ← pytest suite
```

## 2. Your first sprite (10 seconds)

```bash
python3 cli.py "a golden sword, glowing" -o sword.png
```

Done — `sword.png` is a crisp 128×128 sprite (16×16 pixels at 8× zoom,
transparent background).

## 3. What can I ask for?

**Objects (23 families):** sword · dagger · shield · staff · potion · vial ·
chest · coin · gem · key · apple · bread · oak tree · pine tree · bush ·
rock · grass/stone/water tile · fireball · house

**Attributes that actually change pixels:**

| Say | Effect |
|---|---|
| `golden / iron / crystal / ruby / emerald / wooden / copper` | recolors the material |
| `upright` / `lying sideways` | rotates key/key/sword orientation |
| `glowing` | adds white specular shine |
| `with moss` / `with berries` / `autumn` | adds the detail |
| `big` / `small` | scales fireballs |
| `slate roof` / `terracotta roof` | house roof color |

Free phrasing is fine — *“one sword of the crystal kind”*, *“a sword made of
pure iron”*, *“cottage with terracotta roof”* all work.

## 4. Variations & sprite sheets

```bash
python3 cli.py "an iron chest" --variations 4 --sheet variants.png
```

One PNG containing 4 sampled takes on your prompt — perfect for picking a
favorite or filling a tileset row.

## 5. Ask-first mode (chatbot style)

```bash
python3 cli.py --ask "can you animate a walking cycle?"
# → refusal: "i only make 16x16 pixel-art sprites ... no photos, 3d,
#    animation files, logos or other resolutions."

python3 cli.py --ask "draw a blorp"
# → clarify: "i don't know that object yet. i can draw: sword, dagger, ..."
```

The model knows what it doesn't know — it asks instead of hallucinating.

## 6. Python API

```python
from pxg_tiny.pipeline import PXGPipeline

pipe = PXGPipeline()                     # loads ./weights

grid, meta = pipe.generate_pixels("a ruby potion that glows", seed=7)
print(meta)                              # {'gate': 'accept', 'attempt': 0, ...}

# raw 16x16 palette-index grid if you want the pixels yourself:
# grid[y][x] == 0 → transparent, 1..31 → palette color

msg = PXGPipeline.ask("a 4k photo of a cat")   # → refusal message string
```

Deterministic: same prompt + same seed ⇒ same sprite, forever, on any machine.

## 7. Batch generation

```bash
cat prompts.txt
# golden dagger, upright
# slim vial of the slime kind
python3 cli.py --sheet-from-prompts prompts.txt --outdir sprites/
```

## 8. Troubleshooting

| Symptom | Meaning | Fix |
|---|---|---|
| `"gate": "clarify"` | object/attribute unknown | pick from the list it gives you |
| `"gate": "refuse"` | out of scope (3D/photo/animation/other sizes) | rephrase as a 16×16 sprite |
| `"gate": "accept_degraded"` | sprite returned but a check stayed red after 8 tries | usually still usable; try another seed |
| wrong material color | rare sampling drift | retry, or bump `--seed` |

*Everything runs 100% locally — no network, no accounts, no API keys.*