Metadata-Version: 2.4
Name: godice-overlay
Version: 0.1.0
Summary: OBS streaming overlay for GoDice Bluetooth dice
Author: Piotr 'Piotron' Radosz
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: bleak>=3.0.2
Requires-Dist: godice>=0.1.2
Requires-Dist: nicegui>=2.0
Requires-Dist: platformdirs>=4.9.6
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# GoDice Overlay

OBS overlay that shows your [GoDice](https://particula-tech.com/pages/godice) rolls on stream. You roll the physical die, the value pops up in OBS.

Supports all die types (D4, D6, D8, D10, D10X, D12, D20), multiple dice at once, and reconnects automatically if a die drops out.

## What it does

- Connects to GoDice over Bluetooth, shows rolls as an animated OBS browser source
- Comes with 4 themes (Minimal, Neon, Classic, Parchment)
- Detects fake rolls (dropped, not actually thrown) and suspicious ones (moved before settling). You pick what to do with them: ignore, show a warning, or just treat them as normal
- LED feedback on roll: die color, white, or crit mode (green on max, red on min)
- Warns you when battery is low (red LED on the die)
- Keeps roll history in SQLite, exportable to CSV
- Admin UI for managing everything

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/)
- Bluetooth adapter (BLE)
- GoDice dice

## Install

```bash
git clone <repo-url>
cd godice-overlay
uv sync
```

Or just run it directly:

```bash
uvx godice-overlay
```

## Run

```bash
uv run godice-overlay
```

Opens a server on `localhost:8080`:

- `/` is the admin page where you scan for dice, connect them, tweak settings, and check roll history
- `/overlay` is the transparent page you point OBS at

### OBS setup

1. Run `uv run godice-overlay`
2. Add a Browser Source in OBS
3. URL: `http://localhost:8080/overlay`
4. Match width/height to your canvas (1920x1080 or whatever you use)
5. That's it

### Admin page

From the admin page you can:

- Scan and connect dice
- Label them, pick colors, set die types
- Pick a theme, overlay position, text size, how long the roll stays on screen
- Choose LED mode (off, die color, white, crit)
- Decide what happens with fake/suspicious rolls
- Browse the roll log, export to CSV

## Where stuff lives

- Config: `~/.config/godice-overlay/config.yaml`
- Roll database: `~/.local/share/godice-overlay/rolls.db` (rolls older than 30 days get cleaned up)
- Logs: `~/.local/state/godice-overlay/logs/`

## Dev

```bash
uv run pytest
uv run godice-overlay
```

## Built with

- [NiceGUI](https://nicegui.io/) for the UI
- [godice](https://github.com/ParticulaCode/GoDicePythonAPI) for talking to the dice over BLE
- [bleak](https://github.com/hbldh/bleak) for Bluetooth
- [aiosqlite](https://github.com/omnilib/aiosqlite) for the roll database

## License

MIT. Note that the [godice](https://github.com/ParticulaCode/GoDicePythonAPI) dependency has its own [proprietary license](https://github.com/ParticulaCode/GoDicePythonAPI/blob/main/LICENSE.md) that restricts usage to personal and academic purposes.
