# Bonus Roll Tracker

Bonus Roll Tracker is a beginner-friendly World of Warcraft retail addon. It records bonus roll results when WoW fires bonus-roll events, saves them, and shows them in a small in-game popup.

This addon is being shaped for CurseForge distribution.

Important limitation: the addon cannot automatically recover bonus rolls or loot received before it was installed. It can only record events it sees after installation. To handle older items, you can manually add items you already received.

## What an addon needs

A basic WoW addon is just a folder containing:

- A `.toc` file with addon metadata and the list of files to load.

- One or more `.lua` files with the addon code.

For this sample:

```text

BonusRollTracker/

BonusRollTracker.toc

BonusRollTracker.lua

```

The folder name and `.toc` filename must match exactly:

```text

BonusRollTracker/BonusRollTracker.toc

```

## Install it

Copy the `BonusRollTracker` folder into your retail addon directory:

```text

World of Warcraft/_retail_/Interface/AddOns/BonusRollTracker

```

Then start or restart WoW. On the character select screen, click `AddOns` and make sure `Bonus Roll Tracker` is enabled.

## Confirm the current retail Interface number

This starter currently uses:

```text

## Interface: 120005

```

WoW patches can change this number. To check your exact client, type this in the in-game chat box:

```text

/dump select(4, GetBuildInfo())

```

If the number is different, update `BonusRollTracker/BonusRollTracker.toc`.

## Try it in-game

After logging into a character, use these commands:

```text

/brt

/brt help

/brt rolls

/brt current

/brt add

/brt have

/brt want

/brt wishlist

/brt browse

/brt clear

/brt test

```

`/brt rolls` opens the popup. `/brt test` adds a fake entry so you can test the window without waiting for a real bonus roll.

To manually add an item you already received before installing the addon, type `/brt add ` and then shift-click the item into chat:

```text

/brt add [Item Name]

```

To see saved items for only your current dungeon, raid, or zone:

```text

/brt current

```

Every recorded bonus roll is saved for your account using `SavedVariables`.

## Wishlist and chance estimates

You can add wishlist items from outside an instance. Use semicolons to separate the location, item, and total number of rollable items in that location:

```text

/brt want Location Name ; [Item Name] ; TotalRollableItems

```

Example:

```text

/brt want Test Dungeon (Heroic) ; [Really Cool Sword] ; 8

```

You can also record items you already own from outside the instance:

```text

/brt have Location Name ; [Item Name]

```

Then view your wishlist chance estimates:

```text

/brt wishlist

```

Or filter to one location:

```text

/brt wishlist Test Dungeon (Heroic)

```

The chance estimate is:

```text

1 / remaining unowned rollable items

```

For example, if the instance has 8 rollable items and you have already recorded 3 owned items, the addon estimates a wanted unowned item as `1 / 5`, or `20%`.

This assumes each remaining rollable item is equally likely. Real WoW loot rules may be more complicated, so treat this as planning help, not a guaranteed drop-rate calculator.

## Clickable instance and loot browser

Instead of typing location and item names, open the browser:

```text

/brt browse

```

The browser shows dungeon or raid instance images from the Encounter Journal. Click an instance to show its loot list.

In the loot list:

- Left-click an item to add it to your wishlist.

- Right-click an item to mark it as already owned.

When you add wishlist items this way, the addon uses the Encounter Journal loot count as the total rollable item count for the chance estimate.

## What the addon records

When `BONUS_ROLL_RESULT` fires, the addon saves:

- Date and time.

- Current dungeon, raid, or zone name.

- Difficulty name if WoW provides one.

- Last completed encounter name if WoW fired `ENCOUNTER_END`.

- The item, currency, money, or result text from the roll.

- Whether the entry came from an automatic bonus roll event or was added manually.

Retail WoW does not use bonus rolls for every current activity. If the game does not fire `BONUS_ROLL_RESULT`, the addon cannot know that a bonus roll happened.

## Previous items

The addon cannot scan your account and prove exactly what dropped from old bonus rolls. WoW addons generally do not get a complete historical loot record from before they were installed.

Instead, use manual entries:

```text

/brt add [Item Name]

```

Manual entries use your current dungeon, raid, or zone when you add them. This lets you build a "already received from this instance" list over time.

## Build a CurseForge zip

Run this from the repository root:

```powershell

.\scripts\package.ps1

```

If Windows blocks scripts on your machine, use this one-time command instead:

```powershell

powershell -ExecutionPolicy Bypass -File .\scripts\package.ps1

```

The script creates:

```text

dist/BonusRollTracker-0.1.0.zip

```

Upload that `.zip` file to CurseForge. Do not upload the whole repository folder.

The zip contains this structure, which is what WoW and CurseForge expect:

```text

BonusRollTracker/

BonusRollTracker.toc

BonusRollTracker.lua

```

## CurseForge project setup notes

When creating the project on CurseForge:

- Game: `World of Warcraft`

- Project type: `Addons`

- Flavor/game version: `Retail`

- License: `MIT`

- Initial file: `dist/BonusRollTracker-0.1.0.zip`

- Changelog: use `CHANGELOG.md`

CurseForge reviews new projects and files before they appear publicly.

## Beginner editing loop

1. Edit `BonusRollTracker.lua`.

2. Save the file.

3. In WoW, type `/reload`.

4. Test your command again.

Most addon development is this loop: edit, save, reload, test.

## Good first experiments

- Change the login message.

- Add a new slash command like `/hr version`.

- Change the popup size.

- Add columns for character name or loot specialization.

- Add an item-remove command for mistakes.

- Pull possible item pools from the Encounter Journal instead of entering totals by hand.

- Add a search box to the clickable loot browser.

- Store another saved value in `BonusRollTrackerDB`.

## Useful references

- Warcraft Wiki TOC format: https://warcraft.wiki.gg/wiki/TOC_format

- Current Interface number notes: https://warcraft.wiki.gg/wiki/Getting_the_current_interface_number

- WoW API browser: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API

## Project documentation

- User workflow chart: `docs/USER_WORKFLOW.md`