Metadata-Version: 2.4
Name: clilc
Version: 0.1.0
Summary: A neon-synthwave loot-box opener for your terminal — a Textual TUI.
Author-email: ChomChomp <alexboyd540@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ChomChomp/CLILootCollector
Project-URL: Repository, https://github.com/ChomChomp/CLILootCollector
Project-URL: Issues, https://github.com/ChomChomp/CLILootCollector/issues
Keywords: tui,terminal,textual,game,loot,cli,voxel
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# ✦ CLI Loot Collector ✦

A neon-synthwave **loot-box opener** for your terminal, built with
[Textual](https://textual.textualize.io/). 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.

![main screen](tools/preview_1_main.png)

## Install

```bash
pipx install clilc
loot
```

(or `pip install clilc`, then run `loot`). [pipx](https://pipx.pypa.io/) 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

```bash
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.
