RaidKit · In-game addon
Gargul Persistence Bonus
Unofficial Gargul companion that banks a bonus on soft-reserves you keep losing, and keeps your team's loot ledger.
One person: whoever runs loot in Gargul (the master looter) · In your WoW client next to Gargul; the optional digest pipeline runs in PowerShell on Windows · Nothing. Raiders keep using Gargul as usual and can whisper !pb to see their own bonusesVersion 0.25.6 runs on the author's 25-man TBC team's Monday and Thursday raids; the addon is handed out as a zip by the author and is not listed on any addon site; the optional Watch-PB.ps1 auto-poster is built and tested but not yet running live.
Overview
Gargul Persistence Bonus (GPB) is an unofficial companion addon for Gargul, the loot addon many Classic guilds use for soft-reserve (SR) loot. An SR is a raider's advance claim on one item from a raid; when it drops, everyone who reserved it rolls for it. GPB adds a Persistence Bonus (PB): each raid an SR goes unfilled, the player banks +10 PB on that specific item. Next time it drops, that PB is added to their roll. When they finally win it, the PB on that item resets to zero.
Only the master looter installs it. When Gargul sorts the SR rolls, GPB re-sorts by roll plus PB on that one client, shows the adjusted total in the Roll column and the raw roll and bonus in the Note column, and records the award. Nobody else needs the addon, GPB never edits Gargul's files, and other raiders' clients are untouched.
Around that core it grows into a loot officer's toolkit: a per-team loot ledger recorded automatically from Gargul awards, equipment-slot locks for the phase, automatic checks on every imported SR sheet, boss-kill counts, crafted-item locks, multi-team profiles, officer-to-officer sync, a 20-step undo, and a pug mode that holds PB whenever a non-guild player has the top raw roll. An optional PowerShell pipeline reads the addon's saved data after you reload and posts one compact Raid Night Digest to Discord and rebuilds a shared Google Sheet.
GPB is not affiliated with, endorsed by, or maintained by the Gargul project. Gargul is a separate project by its own authors and is a required dependency. The repo carries its own test battery (test/run_all.sh: a Lua 5.1 syntax gate, Lua micro-suites sliced verbatim from the addon source, and a PowerShell suite for the watcher), described in docs/TESTING.md.
What it does, in detail
What a Persistence Bonus is
A soft reserve is a pre-raid claim on one item. When several raiders reserve the same item and it drops, they all roll, and the highest roll wins. Over a phase the same player can lose that roll every single week and walk away with nothing. GPB gives that player a Persistence Bonus: +10 PB on that item for every raid where their SR was not filled. The amount is configurable; 10 is the default. The Menu > Settings > PB increment prompt accepts a whole number from 1 to 1000, while the /pb increment slash command accepts any number of 0 or more and only rejects negatives.
PB is per player, per item, per team. Holding 40 PB on a trinket does nothing for your roll on a belt. The moment you win the item, that item's PB resets to zero, and only that item's.
How the roll adjustment works
GPB wraps one Gargul function, the one that builds the sorted SR roll table, and listens to four Gargul events (item awarded, unawarded, award edited, SoftRes imported). Nothing else in Gargul is touched. On the master looter's client, each eligible player's PB is added to their roll; the Roll column shows the adjusted total and the Note column shows PB +X and the raw roll. The note also reads won <date> for a roller who already won that item this phase, and PB held (in red) for a player you marked ineligible. A companion Roll Monitor window opens during roll-offs with Roll, PB and Total columns and marks the winner; closing it mutes it for that roll-off only, and /pb rollmonitor with no argument brings it back.
Pug mode (default on) protects players who are not in your guild and have no idea PB exists. Pugs always roll raw and never receive PB. If a pug ties or beats the best guild raw roll, PB is held for everyone and the note reads PB +X held (pug). If a guild member holds the strictly highest raw roll, PB is applied among the guild members. Non-guild regulars can be marked as friends with /pb friend so the rule treats them as guild.
With /pb announce on, a PB-adjusted win is posted to raid chat as Persistence Bonus: [item] to Player - roll 74 + 20 PB = 94. Enable that on the master looter's client only. Raiders can whisper !pb to the loot master's character and get their own PB list back, rate limited to one reply per sender every 10 seconds.
The loot ledger and locked slots
Every SR, MS (main spec), OS (off spec) and DE (disenchant) award Gargul hands out is written to the team's loot ledger, deduplicated by Gargul's checksum so a re-award or edit does not double-count. DE rows have no owner; they exist so drop totals and kill dates stay right. From the ledger GPB derives slot locks: an SR or MS win locks that equipment slot for the rest of the phase, so the winner cannot soft-reserve another item for it. OS wins never lock. Main hand and off hand are independent; two-handers show under both and are tagged [2H]; rings and trinkets read 1 of 2 until both are used.
/pb loot opens the ledger in the copy/paste export window: a bare /pb loot shows the view picker, /pb loot item tempest shows one raid by item and /pb loot player groups by player. /pb slots opens the Locked Slots report in the same window, and the Loot History button in the roster window shows all three views with a Back button. Crafted items can be added with /pb craft so a guild-made piece locks its slot exactly like a raid win.
SR sheet checks and phase awareness
After every Gargul SoftRes import (and on /pb checksr) GPB checks the sheet per raid: repeat SRs of items the player already won, SRs into locked slots, players over the per-raid SR limit (default 2), and players with fewer SRs than the limit, listed as X of 2 SRs with what they have, so a player with one SR is flagged as well as a player with none. A trust gate ignores a foreign sheet that contains no current team member, so importing a friend's pug sheet does not rewrite your roster; the one exception is an empty roster, where the first import always bootstraps the team, so import your own sheet before anyone else's. Legitimate repeats are approved with /pb allowrepeat.
A built-in raid-to-phase table (Karazhan, Gruul's Lair and Magtheridon's Lair are phase 1; Serpentshrine Cavern and Tempest Keep are 2; Hyjal Summit, Black Temple and Zul'Aman are 3; Sunwell Plateau is 4) lets an imported sheet detect a new tier. The phase bumps, the phase start date resets to today, and the active raid set is rebuilt from the sheet, so old-phase wins stop counting toward slot locks and repeat flags. The ledger history is kept. /pb activeraids remove is the manual way to take a raid back out of the set.
Pug-night protection and history backfill
If your character also runs outside pugs, flip Track loot on this character off under Menu > Settings before you join. It is on by default. While off, live Gargul awards are ignored, boss kills are not counted, PB is not applied to rolls, and SR imports do not change the roster or phase. The toggle records a timestamped no-track window (the addon keeps the 40 most recent), and login warns loudly until you turn it back on.
/pb importwins backfills the ledger from Gargul's own award history (team players only unless you add everyone), skipping anything inside a no-track window. /pb histaudit YYYY-MM-DD x-rays one date of Gargul history and explains, entry by entry, why each award did or did not import.
Teams, sync, undo and the audit log
Each raid team gets its own PB and ledger database via /pb team. Settings such as increment and phase state are global. If the master looter changes, /pb sync send transfers the PB database to another officer over hidden addon messages: the increment, PB points, ineligibility flags, friends, session awards, approved repeats and the loot ledger (player, item, timestamp, kind and checksum). Boss kills, the last Add Raid receipt, learned classes, phase settings and no-track windows stay on your client. The receiver must run /pb sync accept, and applying it takes an undo snapshot.
/pb undo reverts the most recent change this session, up to 20 steps deep, including a double Add Raid or an applied sync; it refuses to undo a change made on a different team. Every PB change is audit-logged with a timestamp (the last 800 entries); /pb log prints the 10 most recent lines (or the count you give it) and /pb export log opens the full thing.
The Raid Night Digest pipeline
The addon has no network access, so the team-facing half is a PowerShell script. Post-PB.bat runs Post-PBWebhook.ps1, which reads the addon's SavedVariables file directly, auto-discovers your WoW install and account, asks for webhook and sheet URLs once (a skipped answer is saved too and never asked again), and stores them in pb-webhook-config.json beside the script. It rejects a webhook URL that is not on discord.com or discordapp.com and a sheet URL that is not on script.google.com. It then posts one Raid Night Digest to Discord: PB earned per player with running totals, SR won and reset, no PB (ineligible), no PB (absent), and the night's item distribution. Since 0.25.6 the PB earned lines are checked against the live ledger, so a grant you zeroed in game after Add Raid is dropped and noted. Posting is idempotent per receipt.
The same run rebuilds a Google Sheet through an Apps Script web app: PB, Loot, Slot and Raid lookup tabs with dropdowns, raw data tabs, hidden SlotMatrix and RaidMatrix tabs that feed the lookups, per-raid catalog tabs with kill counts, and archived old-phase tabs. Tabs for raids the addon never tracked are deleted rather than archived. Running the script by hand with -CsvDir writes PB.csv, PhaseLoot.csv and LockedSlots.csv; neither .bat file does that. Watch-PB.ps1, optional, watches the SavedVariables file and runs the pipeline for you when a new Add Raid receipt lands, logging every decision to Watch-PB.log beside the script (self-rotated at 2 MB), so raid night ends at clicking Reload now.
What it does not do
GPB does not track attendance (out of scope by design; players with no SRs stay on the team as empty roster stubs), does not replace Gargul's own SR broadcast or tooltips, and does not decide whether a second one-hander for a dual-wielder should lock; that stays a manual judgment call. PB values are visible only where you choose to post them.
Functions
Features
- Persistence Bonus on SR rolls
- +10 PB per raid per unfilled soft reserve (amount configurable: 1-1000 from the settings prompt, any number 0 or higher from /pb increment). Added to the roll on the master looter's client; Roll column shows the total, Note column shows PB +X and the raw roll, plus won <date> for a prior winner and PB held for an ineligible player. Resets on win, for that item only.
- Pug mode
- Default on. Pugs always roll raw. If a pug ties or beats the best guild raw roll, PB is held for everyone (PB +X held (pug)); if a guild member has the strictly highest raw roll, PB applies. /pb friend counts a non-guild regular as guild.
- Add Raid PB dialog and night receipt
- One button at the end of the night. Pick the raids on the sheet (auto-detected), All raids, or only players currently in the group. Produces a copy-paste receipt (granted, SR won, ineligible, filtered, absent) saved for the digest, then prompts Reload now so the data reaches disk.
- Loot ledger and locked slots
- Every SR, MS, OS and DE award recorded per team from Gargul events, checksum-deduplicated; DE rows are ownerless and only feed drop totals and kill dates. SR and MS wins lock the slot for the phase; OS never locks; main hand and off hand independent; 2H tagged under both; rings and trinkets 1 of 2.
- Automatic SR sheet checks
- After every Gargul SoftRes import: repeat SRs of won items, SRs into locked slots, players over the SR limit (default 2), players with fewer SRs than the limit (including none). Foreign sheets with no team member are ignored unless the roster is still empty.
- Phase awareness
- Built-in raid-to-phase table detects a new tier from an imported sheet, bumps the phase, resets the active raid set and slot locks, and keeps the ledger. Old-phase PB is filtered out of everything posted.
- Boss kill tracking
- Counts raid boss kills from ENCOUNTER_END (5-man bosses excluded via the catalog), merged with drop-date inference from the ledger. Seed a count, audit dates, or return a boss to automatic.
- Crafted-item locks
- /pb craft records a guild-crafted item so it locks its slot for phase SRs like a raid win. Reversible with /pb craft remove or /pb undo; /pb craft cancel closes the dialog.
- Track loot on this character
- Per-character toggle for pug nights, on by default. While off, awards, kills, roll decoration and SR imports are ignored, and a no-track window (up to 40 kept) keeps later backfills clean. Login nags while it is off.
- Gargul history backfill and audit
- /pb importwins rebuilds the ledger from Gargul's award history; /pb histaudit YYYY-MM-DD shows one date entry by entry with the reason each did or did not import.
- Roster window
- /pb ui: toggles for PB enabled, pug mode, announce and !pb whispers; By Player and By Item tabs; INCREMENT and PHASE status strip (read-only, with tooltips pointing to the setting); class-colored names; per-row eligibility switch, Guild/Friend, Craft and Remove; footer with SRs, Add Raid PB, Undo, Loot History, Export, Sync, Menu and Refresh. Resizable from 665x420 to 1100x900.
- Menu
- Menu > Roster: Add Friend, Clear PUGs, Clear Roster, Clear PB. Menu > Settings: Track loot on this character, Pug mode (hold PB behind pugs), Roll Monitor, Roll Monitor sorts by raw roll, PB increment, Phase start date, SR limit per raid. Menu > Tools: Record crafted item (how-to), Roll Monitor demo, Reload UI (saves data).
- Roll Monitor
- Auto-opens during Gargul roll-offs with Roll, PB and Total columns and a winner mark. Sort by raw or total; closing it mutes it for that roll-off only; /pb rollmonitor re-shows it and /pb rollmonitor test opens it with demo data.
- Teams
- Separate PB and loot ledger databases per raid team with /pb team or the Team picker in the window. Creating a team switches to it at once.
- Officer sync
- /pb sync who pings one channel for other GPB users (raid if you are in a raid, otherwise party, otherwise guild); /pb sync send transfers the PB database (increment, points, eligibility, friends, session awards, approved repeats, loot ledger); the receiver runs /pb sync accept. Team-aware, audit-logged, undoable.
- Undo and audit log
- 20-step undo for this session, including a double Add Raid or an applied sync. Every change logged with a timestamp, last 800 entries; /pb log shows 10 by default.
- Exports
- Discord code-block tables, CSV, markdown that renders in Discord, a ready-to-post webhook JSON payload (/pb export json), and the audit log (/pb export log), optionally filtered to one item or player.
- Raid announcements and !pb whispers
- Optional raid-chat line when a PB-adjusted roll wins (master looter only). Raiders who whisper !pb get their own PB list back, one reply per 10 seconds per sender.
- Built-in raid loot catalog
- 828 entries covering every TBC raid from Karazhan to Sunwell Plateau, so exports and the sheet resolve item names before an item has ever dropped. Gaps can be filled by CSV import (ItemID,ItemName,Raid,Boss) or by hand with /pb name.
- Minimap button
- Click toggles the roster window, right-click opens the Menu, drag moves it; its position around the minimap persists. /pb minimap hides or shows it.
- Raid Night Digest pipeline
- Post-PB.bat reads SavedVariables, posts one compact digest to Discord and rebuilds the Google Sheet lookups. CSVs are written only when you run the script by hand with -CsvDir. Idempotent per receipt; reconciled against the live ledger since 0.25.6.
- Watch-PB.ps1 auto-poster
- Optional watcher that runs the pipeline when a new Add Raid receipt appears on disk. Ignores mid-raid reloads, never double-posts, holds split nights until the closing unfiltered Add Raid, logs to Watch-PB.log (rotated at 2 MB). Built and tested, not yet armed by the author.
Slash commands
| Command | What it does |
|---|---|
| /pb help | Print the full command list in chat. /gpersist is a second alias for /pb; every command below works with either. |
| /pb ui | Open the roster window. Alias /pb roster. |
| /pb status | Show all stored Persistence Bonuses on the active team. Add an item ID to narrow it. Aliases /pb list, /pb show. |
| /pb item 32837 | Show PB for one item by item ID. |
| /pb player Playername | Show PB for one player (replace Playername with the character's name). |
| /pb addraid | Grant the night's PB for every unfilled SR (same as the Add Raid PB button). /pb addraid tempest filters to one raid; /pb addraid present grants only to players currently in the group (here and ingroup also work). Aliases /pb close, /pb closeweek. |
| /pb set Player 32837 20 | Set a player's PB on an item. Setting 0 creates a bare roster stub without granting PB. |
| /pb add Player 32837 | Add PB to a player on an item; defaults to the increment. Append an amount to override. |
| /pb reset Player 32837 | Reset a player's PB on one item to 0. |
| /pb ineligible Player | Player cannot earn or apply PB until you make them eligible again. Their roll note reads PB held. |
| /pb eligible Player | Lift an ineligible flag so the player earns and applies PB again. |
| /pb friend Player | Treat a non-guild regular as guild for the pug rule. |
| /pb unfriend Player | Remove a player from the manual friends roster. |
| /pb friends | List the manual friends roster. |
| /pb remove Player | Delete a player's PB, eligibility and roster flags on this team. Alias /pb removeplayer. |
| /pb clearpoints | Wipe all PB on the active team (eligibility and roster kept). Aliases /pb clearall, /pb clearpb. Related: /pb clearpugs, /pb clearroster, /pb clearloot (alias /pb clearledger), /pb clearraid, /pb clearineligible. All undoable. |
| /pb loot | Open the loot ledger view picker in the copy/paste window. /pb loot item tempest shows one raid by item; /pb loot player groups by player. Aliases /pb history, /pb loothistory. |
| /pb slots | Open the Locked Slots report: which equipment slots each player's phase wins have locked. Alias /pb lockedslots. |
| /pb bosskills | Combined kill counts per boss. /pb bosskills dates Vashj lists drop dates; /pb bosskills set 5 Vashj seeds a count; /pb bosskills auto Vashj returns it to automatic. Alias /pb kills. |
| /pb histaudit 2026-09-03 | X-ray one date of Gargul history: item, boss, winner and why each entry did or did not import. |
| /pb craft Player [item link] | Record a guild-crafted item that locks its slot for phase SRs (shift-click the item into chat). /pb craft remove Player [item link] reverses it; /pb craft cancel closes the Craft dialog. |
| /pb rollmonitor | Re-show the Roll Monitor after you closed it during a roll-off. /pb rollmonitor test opens it with demo data; /pb rollmonitor on and /pb rollmonitor off toggle auto-open; /pb rollmonitor sort raw and /pb rollmonitor sort total pick the sort. Alias /pb rolls. |
| /pb importwins all | Backfill the ledger from all of Gargul's award history, team players only. /pb importwins 30 limits to 30 days; add everyone to include non-team winners. |
| /pb checksr | Run the SR sheet check now (it also runs automatically after every import). Alias /pb srcheck. |
| /pb srlimit 2 | Maximum SRs per raid before a player is flagged (default 2). |
| /pb phasestart 2026-08-27 | Wins before this date are ignored by repeat and slot flags. /pb phasestart clear removes it. Alias /pb phase. |
| /pb activeraids list | Show which raids' wins count for slot locks and repeat flags. /pb activeraids remove tempest takes one out; add and clear also exist. Alias /pb raidset. |
| /pb allowrepeat Player 32837 | Approve a repeat SR on an item the player already won. |
| /pb disallowrepeat Player 32837 | Revoke an approved repeat. Alias /pb revokerepeat. |
| /pb undo | Revert the most recent PB change this session (up to 20 steps). |
| /pb log 20 | Print the 20 most recent audit log entries. Without a count it prints 10. |
| /pb export markdown | Open a copy window. Formats: discord (default), csv, markdown, json, log. Filter with item 32837 or player Name. Alias /pb copy. |
| /pb export json | Open a ready-to-post Discord webhook JSON payload (By Player and By Item embeds) in the copy window. |
| /pb export log | Open the full audit log (up to 800 entries) in the copy window. |
| /pb announce on | Post PB-adjusted wins to raid chat. Enable on the master looter's client only. /pb announce off disables. |
| /pb whisper on | Reply to raiders who whisper !pb with their own PB list (default on). /pb whisper off disables. Alias /pb whispers. |
| /pb sync who | Ping one channel for other GPB users: raid if you are in a raid, otherwise party if grouped, otherwise guild. Then /pb sync send Player, and on the other side /pb sync accept or /pb sync deny (alias reject); /pb sync status shows pending transfers. |
| /pb team list | Separate databases per raid team: /pb team use Name (alias switch), /pb team create Name (aliases new, add; creates and switches at once), /pb team delete Name (alias remove), /pb team rename Old New. Alias /pb profile. |
| /pb pugmode on | PB applies only when a guild member holds the highest raw roll (default on). /pb pugmode off disables. Alias /pb pug. |
| /pb on | Enable applying PB to Gargul rolls. /pb off disables it entirely. |
| /pb increment 10 | Change the per-raid PB amount from chat (default 10). Accepts any number of 0 or more; only negatives are rejected. The Menu > Settings prompt is stricter (whole number 1-1000). |
| /pb accent teal | Change the window accent color. Presets: gold, teal, blue, violet, rose, ember; or any #RRGGBB. /pb accent list shows the presets; /pb accent reset returns to gold. Aliases /pb color, /pb color. |
| /pb classes | Diagnose class coloring for every roster member. /pb class Player Warlock sets a remembered class by hand; /pb class Player clear forgets it. |
| /pb minimap | Show or hide the minimap button. |
| /pb catalog | Show item-name catalog counts. |
| /pb missingnames | List items in the ledger or PB table whose names the catalog cannot resolve. |
| /pb importnames | Open the CSV import window. Format is ItemID,ItemName,Raid,Boss, one item per line, for example 30480,Pendant of the Violet Eye,Example Raid,Example Boss; the Sample button fills that row in. Alias /pb import. |
| /pb name 32837 Item Name | Set one item's name by hand. Alias /pb itemname. |
| Post-PB.bat | Double-click after you reload: posts the Raid Night Digest to Discord and rebuilds the Google Sheet. It never writes CSVs; for those run the script by hand with -CsvDir. Launches Windows PowerShell (powershell.exe). |
| Post-Sheet-Test.bat | Updates only the Google Sheet; posts nothing to Discord and writes no CSVs. Safe to run any time. Uses PowerShell 7 (pwsh) if installed, otherwise Windows PowerShell. |
| Reconfigure-PB.bat | Re-run WoW install and account discovery, choose which saved webhook or sheet URLs to keep or replace, and preview without posting. |
| .\Post-PBWebhook.ps1 -DryRun | Preview the digest payload, post nothing. Other parameters: -SheetOnly, -FullEmbeds, -Team Name, -CsvDir C:\PBExports, -Reconfigure, -WebhookUrl, -LootWebhookUrl, -LockedSlotsWebhookUrl, -SheetWebAppUrl, -SavedVariablesPath, -CatalogPath, and -Flavor with one of _classic_, _classic_era_, _anniversary_, _retail_. |
| .\Post-PBWebhook.ps1 -SheetOnly -CsvDir C:\PBExports | Write PB.csv, PhaseLoot.csv and LockedSlots.csv with no Discord webhook configured (-SheetOnly is what lets the script run without one). |
| powershell -NoProfile -ExecutionPolicy Bypass -File .\Watch-PB.ps1 -DryRun | Rehearse the auto-poster during a raid: it decides and logs to Watch-PB.log but posts nothing. Drop -DryRun to go live. Also -Once, -RunNow, -PostImmediately and -DebounceSeconds 10 (accepts 1 to 300). |
Settings
- PB enabled
- Roster window toggle, also /pb on and /pb off. Master switch for applying PB to Gargul's roll sorting. Default on.
- Pug mode
- Roster window toggle, Menu > Settings > Pug mode (hold PB behind pugs), or /pb pugmode. PB applies only when a guild member or friend holds the highest raw roll; otherwise it is held. Default on.
- Announce wins
- Roster window toggle, also /pb announce. Posts a PB-adjusted win line to raid chat. Default off; turn on for the master looter's client only.
- !pb whispers
- Roster window toggle, also /pb whisper. Replies to raiders who whisper !pb with their own PB list, one reply per sender per 10 seconds. Default on.
- Track loot on this character
- Menu > Settings, per character, default on. Off before a pug run, on afterward. While off, nothing from Gargul enters the team ledger, kill counts or roll decoration, and later backfills skip the window. The addon keeps the 40 most recent no-track windows.
- Roll Monitor
- Menu > Settings, also /pb rollmonitor on and off. Whether the Roll / PB / Total window auto-opens during roll-offs.
- Roll Monitor sorts by raw roll
- Menu > Settings toggle, also /pb rollmonitor sort raw and /pb rollmonitor sort total. Off means the window sorts by total (roll plus PB).
- PB increment
- Menu > Settings > PB increment (whole number 1-1000) or /pb increment (any number 0 or higher). Default 10. Drives Add Raid grants and the +/- row buttons. The INCREMENT stat in the roster window is read-only; its tooltip points you to the setting.
- SR limit per raid
- Menu > Settings or /pb srlimit. Default 2. Players above it, and players below it, are flagged by the SR check.
- Phase start date
- Menu > Settings or /pb phasestart. Wins before this date are ignored by repeat and slot flags. Normally set automatically when a new-phase sheet is imported.
- Active raids
- /pb activeraids. Learned from imported SR sheets; decides which raids' wins count toward slot locks and repeat flags this phase.
- Accent color
- /pb accent. Default gold (#D9A340). Presets gold, teal, blue, violet, rose, ember, or any #RRGGBB. Persisted.
- Window size and minimap button
- Drag the bottom-right grip to resize the roster window (665x420 to 1100x900); size persists. The minimap button toggles the roster window on click, opens the Menu on right-click, and can be dragged around the minimap; its angle persists. /pb minimap hides or shows it.
- Saved data
- Everything lives in WTF\Account\<account>\SavedVariables\Gargul_Persistence.lua, separate from Gargul's own data, and reaches disk only on /reload or logout.
- pb-webhook-config.json
- Written beside Post-PBWebhook.ps1 on first run: SavedVariables path, catalog path, main webhook URL, optional Phase Loot and Locked Slots webhook URLs, Google Sheet web app URL (each saved even when you skipped it, so you are not asked again), and the LastDigestPostedAt stamp. CsvDir is not stored. Change it with Reconfigure-PB.bat. Never share it; it contains your webhook URLs.
How-to guides
01First raid night with Gargul Persistence Bonus
You are the master looter, Gargul and GPB are installed, and your raid's softres.it sheet is ready. This is the whole night.
- 1Before pulling, import the SR sheet into Gargul the way you always do. About a second later GPB runs its check and prints anything odd: repeat SRs of items already won, SRs into locked slots, anyone over the SR limit (default 2), anyone with fewer SRs than the limit. On a first night with an empty ledger expect only the under-limit list.
- 2Approve any repeat you have decided to allow: /pb allowrepeat Player 32837 (use the item ID from the check output).
- 3If someone should not earn PB tonight (late signup, officer call), run /pb ineligible Player now, before the raid, not after Add Raid.
- 4Open /pb ui once and confirm PB enabled and Pug mode are both on. They are on by default.
- 5Raid and run loot through Gargul as normal. When an SR item drops and people roll, the Roll Monitor opens with Roll, PB and Total; Gargul's own roll table on your screen is sorted by total, with PB +X and the raw roll in the note. On night one nobody has PB yet, so the sort matches the raw rolls.
- 6When the raid is done, click Add Raid PB in the window footer (or type /pb addraid). Tick the raids you ran or All raids, then Add PB. Every unfilled SR gets +10 on its item and a receipt appears; copy it if you post manually.
- 7Click Reload now on the prompt. WoW only writes addon data to disk on reload or logout; this step is what makes tonight's PB safe.
- 8If you set up the Discord pipeline, double-click Post-PB.bat. One Raid Night Digest goes to Discord and the sheet rebuilds. Made a mistake? /pb undo in game, /reload, then post.
02Set up your team before the first import
Ten minutes once, so the first sheet import lands on the right team with the right rules.
- 1Log in and check chat for the load line: Gargul PB: loaded. Use /pb help for commands. If it is missing, Gargul is not loaded or not enabled.
- 2If you run more than one raid team on this character, create a profile: /pb team create Wednesday. That creates the team and switches to it in one step; /pb team use Wednesday is only for switching back later. Otherwise everything lives on the default team.
- 3Mark non-guild regulars who should count as guild for the pug rule: /pb friend Player, or the Add Friend button under Menu > Roster.
- 4Open Menu > Settings and check the PB increment (default 10) and the SR limit per raid (default 2). Change them to match your loot rules.
- 5Import your own softres.it sheet into Gargul before anyone else's: with an empty roster the first sheet is always trusted and becomes the team. GPB learns the roster and the current raids and phase from it and runs the SR check.
- 6If your team already has history in Gargul, backfill the loot ledger with /pb importwins all, then review it with /pb loot and /pb slots. Run /pb histaudit 2026-09-03 for any date that looks wrong.
03Set up the Discord digest and Google Sheet
Optional, Windows only. The addon cannot post anything itself; this pipeline reads its saved data after you reload.
- 1In Discord, open the target channel's settings, then Integrations > Webhooks > New Webhook, and copy the webhook URL. Keep it private.
- 2Put Post-PBWebhook.ps1, Post-PB.bat, Post-Sheet-Test.bat, Reconfigure-PB.bat and PB-Sheet-Code.gs together in one folder anywhere on the machine you raid from.
- 3If you want the sheet, build it before the first run so you can paste its URL when asked: create a blank spreadsheet at sheets.new, open Extensions > Apps Script, delete the sample code, paste all of PB-Sheet-Code.gs and save. Then Deploy > New deployment > Web app, Execute as Me, Who has access: Anyone. Copy the URL ending in /exec.
- 4Double-click Post-PB.bat. It finds your WoW install and account (asks if there are several), finds the addon's SavedVariables and RaidLootCatalog.lua, then asks for the main webhook URL, the optional Locked Slots and Phase Loot webhook URLs (Enter posts them to the main webhook) and the sheet /exec URL (Enter means no sheet). Every answer, including a skipped one, is saved to pb-webhook-config.json next to the script and you are not asked again.
- 5Skipped the sheet and want it later? Run Reconfigure-PB.bat, answer n to Keep the saved [4] GOOGLE SHEET web app URL? and paste the /exec URL, or run .\Post-PBWebhook.ps1 -SheetWebAppUrl followed by the URL once. Then share the sheet with your team as Anyone with the link: Editor. The script locks every cell except the lookup dropdowns, and Google does not let Viewers use dropdowns. Pin the link in Discord.
- 6Test without posting: Post-Sheet-Test.bat updates only the sheet, and .\Post-PBWebhook.ps1 -DryRun prints the digest without sending it. No Google account or Discord? .\Post-PBWebhook.ps1 -SheetOnly -CsvDir C:\PBExports writes PB.csv, PhaseLoot.csv and LockedSlots.csv instead; the .bat files never write CSVs.
- 7If you ever paste a newer PB-Sheet-Code.gs, go to Deploy > Manage deployments, edit, New version, Deploy, or the old code keeps running.
04Pugging on a tracked character
Outside runs must not enter your team's loot ledger. The addon cannot tell a pug night from a team night on its own, so you tell it.
- 1Before you join the pug, open Menu > Settings and turn Track loot on this character off. Chat confirms a no-track window has started.
- 2Raid the pug as normal. Gargul awards, boss kills and PB roll decoration are all ignored while the toggle is off, and any SR sheet you import does not touch the roster or phase.
- 3After the pug, turn the toggle back on. If you forget, the next login prints a loud warning.
- 4Later backfills with /pb importwins skip everything inside the window, and /pb histaudit 2026-09-03 labels those entries as skipped.
- 5If you forgot to toggle off first, check the date with /pb histaudit, then clean up with /pb remove Player for pug names or /pb clearloot if the whole night is wrong. /pb undo reverses any step you overreach on.
05Moving to a new raid phase
Slot locks belong to a phase; PB carries over. The turnover is mostly automatic, with two things you must not do.
- 1Before the first new-phase raid, make a copy of the Google Sheet (File > Make a copy) so the old phase is archived for good. The script keeps superseded raid tabs in place and marks them ARCHIVED; only tabs for raids the addon never tracked are deleted.
- 2Keep old-phase raids off the new phase's SR sheet. Any raid on an imported trusted sheet joins the active raid set, and a phase 2 raid on a phase 3 sheet resurrects phase 2 slot locks.
- 3Import the first new-phase sheet into Gargul. GPB sees raids from a higher phase, bumps the phase, sets the phase start date to today and rebuilds the active raid set. Slot locks now count only new-phase wins; the ledger history and every PB value stay.
- 4Check the result with /pb activeraids list, or read the PHASE stat in /pb ui. If a stale raid slipped in, /pb activeraids remove tempest takes it out.
- 5If your rules reset PB per tier, run /pb clearpoints (undoable). If not, leave it; old-phase PB is filtered out of the digest, the sheet and the CSVs automatically.
06Hand loot to another officer
PB lives on the master looter's client. When someone else runs loot, move the database to them first.
- 1Both officers install GPB and log in. On your client run /pb sync who to confirm the other officer answers. The ping goes to one channel only: raid if you are in a raid, otherwise party if grouped, otherwise guild, so group up or make sure you are both ungrouped and in the guild.
- 2Run /pb sync send Player. Chat reports how many entries across how many players are being sent, in chunks, over hidden addon messages. The transfer carries the increment, PB points, ineligibility flags, friends, session awards, approved repeats and the loot ledger; boss kills, the last Add Raid receipt, learned classes, phase settings and no-track windows stay behind.
- 3The other officer runs /pb sync accept (or /pb sync deny). Applying takes an undo snapshot and writes an audit log entry. Sync warns if the team name on the two clients does not match.
- 4The receiver now runs loot as usual. If they also want raid-chat announcements, they run /pb announce on and you run /pb announce off, so only one client posts.
- 5When loot comes back to you, repeat the transfer in the other direction so the ledger stays in one place.
Good to know
- Only the master looter's client needs GPB. PB-adjusted sorting happens there and is invisible to everyone else. If raiders cannot see SRs, that is Gargul's hidden-sheet flag or broadcast permissions, not GPB.
- SavedVariables (WTF\Account\<account>\SavedVariables\Gargul_Persistence.lua) only reach disk on /reload or logout. The order is always: fix in game, /reload, then Post-PB.bat. The script warns if the file looks more than a day old.
- Turn /pb announce on for the master looter's client only, or raid chat gets duplicate lines.
- The Add Raid receipt is a snapshot; the loot ledger is the truth. Mark players ineligible before you run Add Raid. If you zero a grant afterward, the digest drops that line and adds a note, but the receipt still said +10.
- A filtered Add Raid (for example /pb addraid tempest) deliberately does not clear session award tracking. Finish a split night with a plain Add Raid using All raids, or /pb clearraid.
- Old-phase raids must stay off new-phase SR sheets. Importing a sheet that lists one resurrects its slot locks; /pb activeraids remove is the fix.
- With an empty roster any imported sheet is trusted and becomes your team. Import your own sheet first; the foreign-sheet gate only protects a roster that already has members.
- Toggle Track loot on this character off before a pug, not after. Without the no-track window the addon cannot separate the pug night from a team night.
- A second one-hander for a dual-wielder is a manual call. The addon flags it but will not decide for you.
- PB is per item and per team. Switching teams parks everything, and /pb undo refuses to revert a change made on a different team until you switch back.
- /pb increment from chat accepts 0 and values above 1000; only the Menu > Settings prompt enforces 1-1000. Check what you typed.
- Sync moves the PB database, not everything: boss kills, the last Add Raid receipt, learned classes, phase settings and no-track windows stay on the sending client.
- The first-run prompts save a skipped answer too. Press Enter at the sheet prompt once and Post-PB.bat never asks again; add the sheet later with Reconfigure-PB.bat or -SheetWebAppUrl.
- Neither .bat writes CSVs. CSV files come only from running Post-PBWebhook.ps1 by hand with -CsvDir.
- Sheet members need Editor access because Google does not let Viewers use dropdowns; the script locks every other cell. Dropdown picks are shared between people using the same tab at the same moment.
- After pasting a new PB-Sheet-Code.gs you must create a New version under Manage deployments, or the old code keeps running.
- Old-phase PB is filtered out of Discord, the sheet's PB tab and PB.csv, but still lives in the addon and in any archived sheet copy.
- Do not type /pb remove ||de|| to clear disenchant pseudo-winners; the pipes are WoW escape characters. A login migration (0.24.3 and later) removes them for you.
- Watch-PB.ps1 holds the digest on split nights until an unfiltered Add Raid. Pass -PostImmediately if you want a post after every Add Raid.
- An unposted night's receipt is replaced when the next day's Add Raid runs. The PB itself is safe; only the digest for the earlier night is lost, so post every night.
Visuals
Requirements & credits
Requirements
- Gargul v7.7.33 or newer, installed and enabled on the master looter's client (GPB declares it as a hard dependency and will not load without it)
- WoW Classic Anniversary realms, TBC client (Interface 20505)
- Optional pipeline: Windows with Windows PowerShell 5.1 or PowerShell 7; Post-PB.bat launches powershell.exe, Post-Sheet-Test.bat prefers pwsh when installed
- Optional: a Discord webhook URL for the digest and a Google account for the Apps Script sheet. Without a webhook URL the script only runs with -SheetOnly; CSV-only use is .\Post-PBWebhook.ps1 -SheetOnly -CsvDir C:\PBExports from a PowerShell prompt
Credits
- Gargul — The loot addon GPB extends, a separate project by its own authors. Gargul Persistence Bonus is an unofficial companion, not affiliated with, endorsed by, or maintained by the Gargul project; RaidKit is not affiliated with or endorsed by Gargul. GPB wraps one Gargul function and listens to four events; it never modifies Gargul's files.
- AtlasLootClassic — The built-in RaidLootCatalog.lua (828 TBC raid entries) was sourced from the AtlasLootClassic TBC database, a separate addon by its own authors.
- Blizzard Entertainment — World of Warcraft is a trademark of Blizzard Entertainment. RaidKit is not affiliated with Blizzard.
Download & install
Install Gargul Persistence Bonus v0.25.6
Download not published yetFolder: Interface/AddOns/Gargul_Persistence · Interface 20505
- 1There is no public listing. The addon ships as a zip (Gargul_Persistence_vX_Y_Z.zip, with the folder inside) handed out by the author, and the pipeline as a second zip of flat script files.
- 2Install Gargul (v7.7.33 or newer) first if you have not already. GPB declares Gargul as a dependency and will not load without it.
- 3Drop the Gargul_Persistence folder into Interface\AddOns\ so the path is Interface\AddOns\Gargul_Persistence\ with Gargul_Persistence.toc, Gargul_Persistence.lua, UIKit.lua and RaidLootCatalog.lua inside. The folder ships both Gargul_Persistence.toc and Gargul_Persistence_TBC.toc (Interface 20505); leave both.
- 4Enable Gargul and Gargul Persistence Bonus in the AddOns list at the character screen, then log in or type /reload.
- 5Look for the load line in chat: Gargul PB: loaded. Use /pb help for commands. Type /pb ui to open the roster window. Your data is saved to WTF\Account\<account>\SavedVariables\Gargul_Persistence.lua.
- 6Optional pipeline: put the webhook folder (Post-PBWebhook.ps1, Post-PB.bat, Post-Sheet-Test.bat, Reconfigure-PB.bat, PB-Sheet-Code.gs, Watch-PB.ps1) anywhere on the Windows machine you raid from and follow the Discord and Google Sheet guide. Only the loot officer needs any of this; raiders install nothing.
Changelog
- 2026-09-09
- Kit sync, no version bump: the addon's UIKit.lua copy re-synced to the shared kit 1.4.0 (adds an EditBox control built for another addon). No GPB behavior change; test suites green.
- v0.25.62026-09-03
- Script only: the Raid Night Digest's PB earned section is reconciled against the live ledger. A grant zeroed in game after Add Raid, or an item won later the same night, is dropped from the digest and a note says how many lines were left out.
- Addon files carry only the version bump.
- v0.25.52026-09-02
- Loot History views (By Player, By Item, Locked Slots) open in the text window with a Back button returning to the view picker.