# DetentionRolls

Fair, transparent loot rolling for raids. Instead of a loot council, every raider
rolls — but winning an item reduces your **roll power**, making it more likely
someone else wins the next one. Showing up restores it.

Inspired by the quality-of-life features of RCLootCouncil (session automation,
deferred trade tracking, version gating), rebuilt around a weighted rolling
system. Targets WoW Midnight (Interface 120000 / 120100) and is secret-value
safe per the 12.x addon restrictions.

## How rolling works

| Category | Roll range | Roll power? |
|---|---|---|
| BIS / 4-piece / 2-piece / Major Upgrade (need) | 1–200 | Yes — multiplied by your power |
| Offspec (greed) | 1–100 | No — standard flat roll |
| TMOG (cosmetic) | 1–50 | No — standard flat roll |
| Pass | records that you responded, never competes | — |

Contention priority: **BiS > 4-piece > 2-piece > Major Upgrade > Offspec >
TMOG** — any roll in a higher category beats any roll in a lower one.
**Roll power only applies to need rolls**, and only need wins take the
winner penalty; winning offspec or transmog costs nothing.

- Your **effective score** = `floor(baseRoll × rollPower / 100)`. Roll power
  ranges **1–200** with a uniform cap of 200 for everyone; new players start
  at **100**. Power above 100 boosts your rolls.
- **Winning an item**: power = `floor(power × 0.60)` at **reward
  confirmation**, not at resolve — either the leader presses the Reward
  button, or the item is successfully traded to the winner (auto-detected).
  The new authoritative power is broadcast so every raider's display syncs.
- **Concurrent items stay fair**: when a reward confirms, the winner's new
  power immediately propagates into every other open session — collecting
  rolls update their captured weight, and already-awarded (but unrewarded)
  items **re-resolve**, so nobody wins two items at the cost of one penalty.
- **Each boss kill in a designated raid** (see Raid activation): raiders
  **+5**, leader-flagged **Bench** players sitting out **+12.5** — a full
  8-boss clear reproduces the +40 / +100 weekly totals from the Monte Carlo
  tuning. Roster players who are neither in the raid nor benched get nothing.
  Kills gate the credit: a wipe night grants nothing, but costs nothing.
- **No per-night or weekly accrual by default.** Teams that want it can set
  "Weekly Regain" above 0 in options; it applies at the weekly reset
  (Tuesday, 10 AM PST fallback when the game API is unavailable).
- Higher categories always beat lower ones (a BIS 5 beats an Offspec 100).
- Exact ties trigger an automatic roll-off among the tied players.

All factors are tunable in `/droll config` (penalty factor, both regain
rates, weekly regain, starting power, min/cap).

## Anti-tamper design

- **The raid leader's client is the single authority.** It generates every roll
  server-side (leader-side); raiders only transmit their chosen category, so a
  modified client cannot forge a roll value.
- **Sender identity is transport-verified.** Submissions are attributed to the
  actual comm sender Blizzard reports, never to identity claimed inside the
  message payload.
- **Authority messages are leader-gated.** Session init, results, roll-offs,
  rewards and snapshots are only accepted if the verified sender is the
  current group leader; anything else is rejected and audit-logged.
- The roll-power ledger lives on the leader's client; raiders only see a local
  estimate.
- Every state change is appended to a tamper-evident audit log
  (`/droll export`).

The addon icon (`Media/Icon.png`) shows in the AddOn List and the minimap
addon compartment — left-click opens the Loot Rolls window, right-click opens
options. `Drolls.png` in the root is the full-resolution source art (also
usable as the CurseForge/Wago project thumbnail).

## UI

All windows use a custom flat dark style (no stock WoW dialogs), are movable
by dragging their title bar, remember their positions per profile, and close
with ESC.

- **Raider window** (`/droll loot` or `/drollme`, auto-opens when loot
  sessions start): every active item is a card with its icon, link, countdown,
  and per-item roll buttons (BIS / 4p / 2p / Up / OS / TM / Pass). Scroll when
  more items are up. After rolling, an amber **Cancel Roll** button appears
  while the collection window is still open — retract your roll and pick
  again (fixes misclicks and changes of heart). Once a winner exists, the
  item holder gets a **Trade** button on the card: it opens trade with the
  winner (must be within 11 yd), auto-places the pending item(s) into the
  trade window, and attempts to accept. Blizzard hardware-protects the final
  accept, so if it doesn't confirm automatically, click Trade once —
  completing the trade still auto-marks the entry traded and confirms the
  reward.
- **Raid leader window** (`/drollrl`): drag an item from your bags into the
  box (or shift-click a link) to start a session; every session is a card with
  Resolve / Roll-Off / Reward / Archive controls. Clicking a card shows its
  **rolls list**, sorted highest-first in contention order; once awarded, the
  winner pins to the top. Each non-winner row has an **Award** button so the
  leader can re-assign the win (e.g. the winner no longer wants the item) —
  the deferred trade re-targets so the Trade button hands it to the right
  player. Re-awarding is possible until the reward is confirmed. Items also
  **auto-populate**: when the leader opens a loot window, epic+ items
  automatically get sessions (threshold configurable).
- **Roster window** (`/droll roster` or `/drollroster`): tracked players with
  class-colored name, roll power, addon version, and their response status in
  the current session. Current group members always show; tracked players
  outside the group show dimmed.
  - **Add Group** tracks everyone currently in your raid — only tracked
    players are stored in the roster and exported. It is purely additive:
    players tracked from previous raid nights keep their entry and roll power
    even when absent today.
  - **Send to Raid / Sync from RL** — the leader can broadcast the tracked
    roster (names + roll power) to everyone; raiders can request it. Only a
    broadcast from the verified group leader is accepted, and applying it
    never removes a raider's local extras.
  - **Edit** (per row) manually sets a player's roll power.
  - **B** (per row) toggles **Bench**: benched players earn the higher boss
    credit (+12.5) while out of the raid. Shown as a green `[B]` tag; the
    flag travels with roster syncs and exports.
  - **Roll For** (in the edit bar) opens the **proxy roll window**: the
    leader makes roll choices on behalf of a raider who doesn't run the
    addon — same category buttons per collecting session, with the player's
    current choice shown and cancellable.
  - **x** (per row) stops tracking a player.
  - **Export / Import** opens a text window: Generate Export produces a
    plain-text roster (`guid;name;power` lines) to copy somewhere safe;
    pasting a saved export and pressing Import restores it after data loss.

All roster data is stored locally in the raid leader's SavedVariables
(`WTF\Account\<account>\SavedVariables\DetentionRolls.lua`), account-wide,
written on logout/reload. The export exists as an extra off-game backup.
- **Deferred trades** (`/drolltrade`) and the roll-off popup share the style.
- **Status toolbar** (`/droll bar` to toggle, on by default): slim movable bar
  showing raid-mode Active/Inactive, who the RL is, your current roll power,
  and quick-open buttons for the Loot / RL / Roster / Trades windows. The `L`
  button locks/unlocks dragging; position is remembered per profile.
- `/droll` opens the options in a standalone scrollable window (the embedded
  Blizzard Settings panel squished the controls; the addon still registers
  there for discoverability).

## Commands

| Command | What it does |
|---|---|
| `/droll` | Open the options panel |
| `/droll help` | Command list |
| `/droll loot` | Open the Loot Rolls window |
| `/droll roster` | Roster window (roll power / addon / session status) |
| `/droll test` | Enable test mode + open a test session (works solo) |
| `/droll test fake N` | Inject N fake raider submissions |
| `/droll test resolve` | Resolve the test session immediately |
| `/droll test off` | Disable test mode, purge fake data |
| `/droll ping` | Verify comms: reports who else runs the addon |
| `/droll weight` | Your current roll power |
| `/droll status` | Version-gate status for the raid |
| `/droll export` | Dump recent audit events |
| `/drollrl` | Raid leader window |
| `/drollme` | Raider window |
| `/drolltrade` | Deferred trade tracker |

## Raid activation

Automation only runs in raids the leader has designated. When the group
leader enters a raid instance, a prompt asks **"Run DetentionRolls for this
raid?"** (like RCLootCouncil's usage popup):

- **Yes** — boss-kill roll-power regain, loot auto-add and group-loot
  funneling turn on, and the decision is broadcast to the whole raid (and
  re-announced to late joiners).
- **Not this raid** — everything stays off; normal Blizzard loot, no regain.

The decision is remembered per instance (survives /reload) and resets when
you leave. Manual control: `/droll raid on|off`, status via `/droll raid`.
Only a broadcast from the verified group leader can flip a raider's flag.
Manual sessions and test mode work regardless of activation.

## Group loot funneling (auto-pass)

On by default (toggle in Options → Automation): when a Blizzard group-loot
roll starts, **raiders automatically pass on everything** and the **raid
leader automatically needs everything** (falling back to transmog/greed when
need isn't allowed). Items funnel to the leader's bags and get distributed
through DetentionRolls roll sessions and the deferred-trade queue.

Safeguards:
- Raiders only auto-pass when the group leader is confirmed to be running
  DetentionRolls (version announce received). No addon on the leader = normal
  Blizzard rolls, untouched.
- Legendary-or-better drops and known untradeable items (event hearthstones,
  toys) are never auto-rolled.
- BoP confirmation prompts are auto-confirmed only for rolls the addon
  initiated itself.

## Testing the addon

1. **Solo smoke test:** `/droll test` — opens a 60-second session on a sample
   item and treats you as raid leader. Roll via the raider panel, then
   `/droll test fake 5` to add competition and `/droll test resolve` (or wait
   for the auto-resolve timer). Winner penalty and ledger updates run for real.
2. **Comms test with another player:** group up, both install the addon, run
   `/droll ping`. Each responder is listed with their addon version.
3. **Version gate:** `/droll status` shows whether any raider is missing the
   addon or running an outdated protocol; strict gating blocks session start.

## Session lifecycle

`DRAFT → OPEN → COLLECTING → RESOLVING → (ROLLOFF →) AWARDED → REWARDED → ARCHIVED`

Sessions auto-resolve when the collection timer expires. Winners are announced
over addon comms (with reliable delivery + ACK/retry) and optionally in
raid chat. Won items enter the deferred-trade queue; completing the in-game
trade with the winner marks the entry as traded, which **confirms the reward
and applies the roll-power penalty** — the leader's Reward button does the
same thing manually if trading isn't possible.

## Midnight (12.x) safety notes

- All outgoing comm payloads are scrubbed of secret values before
  serialization (`issecretvalue`/`issecrettable` guards).
- Chat announcements respect `C_ChatInfo.InChatMessagingLockdown()`.
- No aura, combat-log, or restricted-unit APIs are used.
