🎨 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)
# 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)
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
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)
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
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
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.