clilc 0.1.0

A neon-synthwave loot-box opener for your terminal — a Textual TUI.

✦ CLI Loot Collector ✦

A neon-synthwave loot-box opener for your terminal, built with Textual. Chunky pixel-art sprites, a software-3D rotating reward cube, and lots of particle effects — all rendered with half-block characters so it stays crisp in a small terminal window.

Install

pipx install clilc
loot

(or pip install clilc, then run loot). pipx keeps it in its own isolated environment, which is ideal for a command-line app.

Controls

Key	Action
O	Open a loot box
A	Toggle auto-play (auto-opens chests hands-free)
R	Re-drop the gem hoard behind the chest
M	Open the model inspector (cycle every item's 3D model)
Enter / Space	Collect the revealed item & continue
← / →	Cycle models (in the inspector)
Q / Esc	Quit / back

Your collection (items, total value, gear score, best rarity) persists between runs in a per-user data file (~/.local/share/clilc/save.json).

Run from source

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

The three screens

1. Main — an idle treasure chest bobbing in front of a hoard of gems that fall from the top and pile up behind it: one gem per item you've collected, coloured by its rarity. The pile grows by one gem each time you return from a reward, and R re-drops the whole hoard. Your collection stats sit up top. Press O and the chest bursts open with a rarity-coloured particle blast.
2. Looting — a CS:GO-style reel of rarity-tinted gem tiles spins over a "wavey RGB" gradient and decelerates to land your drop under the centre marker.
3. Reward — a rotating 3D cube tinted to the item's rarity with an emissive glow and confetti, beside the item's name, value and gear score.

How the graphics work

Everything visual draws into a Buffer — a 2D grid of RGB pixels — which is streamed to the terminal using the upper-half-block character ▀ (foreground = top pixel, background = bottom pixel). That doubles vertical resolution and gives the chunky-pixel look. Runs of identical cells are merged so flat regions are nearly free to redraw at 30 fps.

Module	Responsibility
loot/pixelcanvas.py	Buffer + PixelCanvas widget (the rendering core)
loot/backdrop.py	animated synthwave sun + perspective grid
loot/sprites.py	procedural chest (with lift-open animation) + gem icons
loot/cube.py	software 3D cube: rotate → project → shade → fill, + glow (fallback)
loot/mesh.py	generic mesh renderer with a per-pixel z-buffer
loot/voxel.py	voxel models, greedy meshing, .vox/.json loaders, item→model map
loot/itemmodels.py	a code-authored voxel model for every item in the pool
loot/models/	drop your own .vox / .json models here (see its README)
loot/screens/inspector_screen.py	the M model inspector
loot/particles.py	particle system (sparkles / burst / confetti fountain)
loot/loot_table.py	rarities, themed item pool, weighted rolls, persistence
loot/screens/	the three Textual screens and the flow between them

Rarities

Common · Uncommon · Rare · Epic · Legendary — each with its own colour, drop weight, glow intensity and confetti volume.

Dev tools

• tools/render_preview.py — renders each scene's pixel buffer to a scaled-up PNG (tools/preview_*.png) for inspecting the art directly.
• tools/drive.py — drives the real app headless through the full flow and saves screenshots, used to verify rendering and screen transitions.

Extending it

This first pass prioritises looking good; it's built to grow. Easy next steps: add items to POOL in loot/loot_table.py, tune rarity weights/colours in loot/palette.py, add new sprite shapes in loot/sprites.py, or add an inventory screen that reads the saved collection.