DragonLoot

Imported from Xerrion/DragonLoot (AGENTS.md). Install upstream with npx skills add Xerrion/DragonLoot. Copyright stays with the author.

DragonLoot AGENTS.md

Target Versions

Version-specific files load via BigWigsMods packager comment directives (#@retail@ / #@non-retail@) in the TOC.

Project Structure

The repository is structured as a multi-addon project separating core logic, configuration companion, and testing/tooling:

• DragonLoot/ (Core Addon)
  • Core/: Core bootstrap (Init.lua), addon lifecycle (Lifecycle.lua), AceDB database configurations, slash commands, and the minimap icon.
  • Display/: Custom loot frames (LootFrame.lua), roll frames (RollFrame.lua), history window (HistoryFrame.lua), and associated UI/layout animations.
  • Listeners/: Event listeners handling version-specific API differences (e.g., LootListener_Retail.lua vs. LootListener_Classic.lua). Uses packager directives (#@retail@ / #@non-retail@) to load correct listeners.
  • Locales/: Localized strings for translation support.
  • Libs/: Embedded external libraries (Ace3, LibSharedMedia-3.0, LibAnimate, etc.).
• DragonLoot_Options/ (Load-on-Demand Configuration)
  • A separate companion addon loaded on-demand when the user opens the options interface.
  • Contains individual tabs for configuring appearance, animations, roll frame, and history settings, and embeds the custom DragonWidgets library.
• spec/ (Testing Suite)
  • Contains the busted unit test suite (Config_spec.lua, Lifecycle_spec.lua, MasterLoot_spec.lua) and a comprehensive WoW API mock harness (wow_mock.lua).

Config Schema Reference

General (db.profile)

Appearance (db.profile.appearance)

Animation (db.profile.animation)

Roll Frame (db.profile.rollFrame)

confirmGreedAndPass asks for confirmation before Greed or Pass is submitted. reverseButtonOrder reverses the roll action button order. resultLingerDuration applies only when keepOpenAfterVote is enabled. showRollTally is available only on Classic (TBC/MoP); Retail removed C_LootHistory.GetItem and GetPlayerInfo in patch 10.1.0.

History (db.profile.history)

Version-Specific API Differences

DragonToast Integration

Messages Sent by DragonLoot

Roll Won Toast Data

{
    itemLink = string,     -- full item hyperlink
    itemName = string,     -- item name
    itemQuality = number,  -- 0-7 quality enum
    itemIcon = number,     -- icon texture ID
    itemID = number,       -- parsed from itemLink
    quantity = number,     -- stack count
    isRollWin = true,      -- suppression bypass flag
    isSelf = boolean,      -- true if current player won
    looter = string,       -- winner's name
    itemType = string,     -- e.g. "Need (87)" for display
    timestamp = number,    -- GetTime()
}

Individual Roll Result Toast Data

{
    itemLink = string,     -- full item hyperlink
    itemName = string,     -- item name
    itemQuality = number,  -- 0-7 quality enum
    itemIcon = number,     -- icon texture ID
    itemID = number,       -- parsed from itemLink
    quantity = 1,          -- always 1
    isRollWin = false,     -- not a win notification
    isSelf = boolean,      -- true if current player rolled
    looter = string,       -- roller's name
    itemType = string,     -- e.g. "Need (87)" or "Greed (42)" for display
    timestamp = number,    -- GetTime()
}

DragonToast Behavior

• DRAGONTOAST_SUPPRESS with source "DragonLoot" sets a suppress flag; item loot toasts are suppressed while DragonLoot's loot window is open
• DRAGONTOAST_UNSUPPRESS with source "DragonLoot" clears the suppress flag
• DRAGONTOAST_QUEUE_TOAST with isRollWin = true triggers a celebration toast
• DRAGONTOAST_QUEUE_TOAST with isRollWin = false triggers a standard item toast (individual roll result)
• XP, honor, currency toasts are never suppressed
• DragonToast's Listeners/MessageBridge.lua handles backward compatibility for old message names (DRAGONLOOT_LOOT_OPENED, DRAGONLOOT_LOOT_CLOSED, DRAGONLOOT_ROLL_WON)

Just Recipes

DragonLoot ships a justfile in addition to .mise.toml.

StyLua config (.stylua.toml): 120-char width, 4-space indent, double quotes, Unix line endings, always parenthesized calls.

Known Gotchas

1. CHAT_MSG_LOOT patterns are localized - parsing requires Lua pattern matching on localized strings
2. Blizzard frame suppression - Must restore events on disable or the default loot window breaks permanently for the session
3. Retail C_LootHistory duplicate events - LOOT_HISTORY_UPDATE_ENCOUNTER re-fires for all drops; use processedDrops dedup table
4. Retail API field names - winner.playerClass not winner.className in C_LootHistory
5. Classic double-open - LOOT_OPENED can fire twice; guard with if isLootOpen then return end
6. Roll data availability - Fetch item info via GetLootRollItemInfo BEFORE calling CancelRoll, as data is lost after cancel
7. Local dev listener loading - Packager directives (#@retail@, #@non-retail@) are plain comments locally, so both Retail and Classic listeners are loaded in dev. IsRetail / IsClassic version guards inside each file ensure only the correct one activates
8. NOTIFICATION_STATE_MAP vs ROLL_STATE_MAP - ROLL_STATE_MAP in HistoryListener_Retail maps Transmog->Greed (lossy) for history display. ns.NOTIFICATION_STATE_MAP in RollManager preserves Transmog as a distinct roll type for notifications
9. Classic LOOT_HISTORY_ROLL_CHANGED timing - May fire before roll value is assigned; ProcessClassicRollResult skips non-Pass rolls with nil roll values and relies on a later re-fire with the value
10. Roll result dedup - Both Retail and Classic listeners use notifiedRollResults tables to prevent duplicate notifications per player per drop; tables are wiped on history clear and shutdown
11. CHAT_MSG_LOOT GlobalStrings differ by version - TBC self-loot patterns have trailing periods, Retail does not. Build patterns from actual GlobalString values at runtime, never hardcode
12. Classic Master Loot No-Payload Constraint - The OPEN_MASTER_LOOT_LIST event has no payload. To handle this, LootFrame.lua:OnSlotClick stashes the slot index in s.pendingMasterLootSlot immediately before calling LootSlot(slotIndex). MasterLootListener_Classic consumes this value during the event. This state is carefully cleaned up on list consumption, window close, or addon disable to prevent dangling/leaking references.

Labels

GitHub Projects

• DragonLoot - Bugs: project #5 (C-Bug issues)
• DragonLoot - Feature Requests: project #4 (C-Feature issues)