Metadata-Version: 2.3
Name: backshot-solver
Version: 0.1.0
Summary: A buckshot roulette magazine predictor
Author: takingurstuff
Author-email: takingurstuff <130810510+takingurstuff@users.noreply.github.com>
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Buckshot Roulette Solver Overlay

A minimal, low-latency, mathematical state-space tracker and HUD overlay for _Buckshot Roulette_ (and its Roblox port _Buckshot_). Tracks exact shell inventory, computes real-time Bayesian chamber probabilities, and incorporates oracle item observations (Magnifying Glass and Burner Phone) using vim-style keybinds. Partially inspired by [BackshotRoulette](https://github.com/redstone59/BackshotRoulette) (redstone59)

---

## Installation

### Via `pipx` or `uv`

```bash
# uv:
uvx backshot-solver

# or pipx:
pipx install backshot-solver
```

### Editable

```bash
git clone https://github.com/takingurstuff/backshot-solver
pip install -e .
```

### Development Install (`uv` recommended)

```bash
git clone https://github.com/takingurstuff/backshot-solver
uv sync
```

---

## How to Use

1. Launch **Buckshot Roulette** in **Borderless Windowed** or **Windowed** mode.
2. Launch the solver:

```bash
backshot-solver
```

_Do note that the overlay pins itself to top for easy accessing_.

3. Enter the initial **Live** and **Blank** shell counts announced by the dealer at the start of the loadout.
4. Click **Initialize**.

---

## Keybinds & Controls

All inputs use modal, vim-style chords. You do not need to click or hold modifier keys:

| Command          | Action                                | Example                            |
| ---------------- | ------------------------------------- | ---------------------------------- |
| `L`              | Register Live shell fired/ejected     | Dealer shoots Live                 |
| `B`              | Register Blank shell fired/ejected    | Dealer shoots Blank or drinks Beer |
| `ML` / `MB`      | **Magnifying Glass** (Top shell type) | `ML` = Top shell is Live           |
| `P<Slot><Type>`  | **Burner Phone** (Forward indexing)   | `P3L` = 3rd shell from top is Live |
| `P-<Slot><Type>` | **Burner Phone** (Backward indexing)  | `P-1B` = Last shell is Blank       |

_Note: If an invalid key or partial chord is abandoned, the input buffer clears automatically after 1.2 seconds._

---

## Compositor Setup (Hyprland)

For Hyprland users, add these rules to `~/.config/hypr/hyprland.conf` to enable opacity and floating:

```ini
windowrulev2 = float, title:^(Buckshot Roulette Solver Overlay)$
windowrulev2 = opacity 0.7 0.7, title:^(Buckshot Roulette Solver Overlay)$
windowrulev2 = noblur, title:^(Buckshot Roulette Solver Overlay)$

```

OR post luafication hyprland:

```lua
hl.window_rule({
    match = {
        title = "^(Buckshot Roulette Solver Overlay)$",
    },
    float = true,
    pin = true,
    opacity = "0.7 0.7",
    no_blur = true,
})
```

---

## Disclaimers

> **Use at Your Own Risk:** This is an external mathematical calculator. While it does not hook into, inject code, or read game process memory, using third-party trackers in online multiplayer mode may be considered unsportsmanlike or breach community guidelines.

> **RNG & Variance:** This tool provides strictly optimal mathematical probabilities based on known information. An $80\%$ chance of a blank is not a $100\%$ guarantee—variance and bad rolls can and will still happen.
