✦ 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

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.

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.