Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 21 additions & 23 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,29 @@ Purpose in one line: a click-to-buff list addon for World of Warcraft — it sho
every nearby player who is missing one of your buffs; click a name (or press one
key) to buff them.

Frozen foundation: one shared Lua source (`BuffRadar/Data.lua` + `BuffRadar/BuffRadar.lua` + `BuffRadar/Coordination.lua` + `BuffRadar/Wizard.lua` + `BuffRadar/Window.lua` + `BuffRadar/Config.lua` + `BuffRadar/Slash.lua` + `BuffRadar/Extras.lua` + `BuffRadar/Recaps.lua` + `BuffRadar/Profiles.lua`) builds both
editions; editions differ only in their `.toc` and bundled docs
(`BuffRadar/` = Retail docs, `editions/forever/` = Forever docs). Every feature
is reachable as a `/br` slash command — the slash surface is the operation
registry — as well as through its settings control where it has one.
SavedVariables are versioned (`dbVersion`, currently 20) with a tested migration
chain; adding or changing a setting is a format change and updates the migration
smoke fixtures in the same change.
Frozen foundation: both editions share the Lua source under `BuffRadar/`.
Their `.toc` files declare load order; do not use `require` or add globals for
module communication. `Data.lua` initializes the addon namespace, `SavedVariables.lua`
owns the schema and publishes the live DB, `BuffRadar.lua` owns scanning and
cast decisions, and `Window.lua` and `Minimap.lua` own their frames and caches.
Keep implementation state local and share entry points through the addon table.
Every feature is reachable through `/br` as well as through its settings control
where it has one. SavedVariables are versioned (`dbVersion`, currently 21) with
migration smoke fixtures; keep those fixtures in sync with format changes.

Build: none (interpreted Lua 5.1).
Full gate (all of it, every time, output read):
`python3 tools/luacheck51.py BuffRadar/BuffRadar.lua BuffRadar/Extras.lua BuffRadar/Locales/*.lua` · (or just `sh tools/gate.sh`; `sh tools/install-hooks.sh` runs it before every push) ·
`python3 tools/lualimits.py BuffRadar/BuffRadar.lua` ·
`python3 tools/localecheck.py BuffRadar/BuffRadar.lua BuffRadar/Locales` ·
real luacheck 1.2.0 over both Lua files (0 warnings / 0 errors) ·
`python3 tools/smoke51.py tools/wowstub.lua BuffRadar/BuffRadar.lua`
(six fake-client setups, 0 errors required).
Test corpus: the trial run in `tools/smoke51.py` — it only grows; every feature
lands with steps in every setup it applies to.

Budgets: the host's per-frame budget governs — scanning is event-driven plus a
throttled ticker; no per-frame polling. Lua 5.1 hard limits enforced by
`tools/lualimits.py`: ≤200 top-level locals (currently 165 in `BuffRadar.lua`), ≤60 upvalues per
function (currently 58 peak, `HandleSlash`). New state goes in the `X` table or methods, never
new file-scope locals, unless the budget is re-checked in the same change.
Full gate (all of it, every time, output read): `sh tools/gate.sh` runs the Lua
5.1 compiler, advisory limit estimates, locale and pattern checks, seven
fake-client smoke setups using the two TOCs, and two-client coordination.
`sh tools/install-hooks.sh` installs the pre-push gate. Also run real luacheck
1.2.0 on all addon Lua files (0 warnings / 0 errors); `tools/check.ps1` runs the
checks on Windows. Add trial steps for every feature in the setups it applies to.

Budgets: scanning is event-driven plus a throttled ticker; no per-frame
polling. The Lua 5.1 compiler enforces 200 active locals per function or chunk
and 60 upvalues per function. Check headroom with `tools/lualimits.py` when
adding file-scope state; keep state in its owning module rather than moving it
into the shared `X` table to work around the limits.

Coverage floors: every user-visible capability has smoke evidence before it is
called done; in-game behaviour is labelled **Unverified** until SEAN's field test
Expand Down
3,202 changes: 622 additions & 2,580 deletions BuffRadar/BuffRadar.lua

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion BuffRadar/BuffRadar.toc
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,12 @@

Locales\deDE.lua
Data.lua
SavedVariables.lua
BuffRadar.lua
Minimap.lua
Coordination.lua
Wizard.lua
Window.lua
Wizard.lua
Config.lua
Slash.lua
Recaps.lua
Expand Down
60 changes: 29 additions & 31 deletions BuffRadar/Config.lua
Original file line number Diff line number Diff line change
@@ -1,32 +1,25 @@
-- BuffRadar - Config: the settings window (widget builders, the five
-- tabs, BuildConfig, RefreshConfig, OpenConfig).
-- Loaded after BuffRadar.lua through the .toc. This is file-split
-- Slice B (1.15.0): the code below is the settings do-block that used to
-- sit at the bottom of BuffRadar.lua, moved verbatim; it reaches the
-- main file's locals through X.cfgAPI, which BuffRadar.lua fills in
-- before this file loads. Settings state (the cfg table and every
-- widget) is local to this file, exactly as it was local to the block.
-- BuffRadar - settings window, controls and keyboard navigation.
-- Copyright (C) 2026 Malikor. GPLv3 or later.

local _, NS = ...
NS = NS or {}
local X = NS.X or {}
NS.X = X
local A = X.cfgAPI or {}
local _, ns = ...
local X = ns.X
local core = X.Core
X.cfgReg = {}

local db -- the live settings table; read fresh at each entry point (X.GetDB)
local L = A.L
local Print, Refresh, PlayAlert = A.Print, A.Refresh, A.PlayAlert
local ApplyAppearance, ApplyGeometry = A.ApplyAppearance, A.ApplyGeometry
local BuildBuffList, InvalidateRows, UpdateCounter = A.BuildBuffList, A.InvalidateRows, A.UpdateCounter
local IsOn = A.IsOn
local KeybindText, OpenKeybinds, MakeMacro = A.KeybindText, A.OpenKeybinds, A.MakeMacro
local RefreshMinimapButton = A.RefreshMinimapButton
local myBuffs = A.myBuffs
local Ignore = A.Ignore
local DEFAULTS, SCALE_PRESETS = A.DEFAULTS, A.SCALE_PRESETS
local CLASSIC_FEATURES = A.CLASSIC_FEATURES
local NEXT_BINDING = A.NEXT_BINDING
local L = X.L
local Print, Refresh, PlayAlert = X.Print, X.Refresh, core.PlayAlert
local ApplyAppearance, ApplyGeometry = X.ApplyAppearance, X.ApplyGeometry
local BuildBuffList, InvalidateRows, UpdateCounter = core.BuildBuffList, X.InvalidateRows, X.UpdateCounter
local IsOn = core.IsOn
local KeybindText, OpenKeybinds, MakeMacro = core.KeybindText, core.OpenKeybinds, core.MakeMacro
local RefreshMinimapButton = X.RefreshMinimapButton
local myBuffs = core.Buffs
local Ignore = X.Ignore
local DEFAULTS = X.Settings.Defaults
local SCALE_PRESETS = { 0.5, 0.75, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2 }
local CLASSIC_FEATURES = X.classic
local NEXT_BINDING = core.NextBinding
local pairs, ipairs, type, tonumber, tostring, pcall = pairs, ipairs, type, tonumber, tostring, pcall
local math_floor, math_min = math.floor, math.min
local table_sort = table.sort
Expand Down Expand Up @@ -700,7 +693,7 @@ local function OpenBlessingPanel()
BackdropTemplateMixin and "BackdropTemplate" or nil)
cfg.blessingPanel, cfg.blessingSelectors = panel, {}
panel:SetPoint("CENTER", cfg, "CENTER")
panel:SetSize(490, 372)
panel:SetSize(490, 392)
panel:SetFrameStrata("DIALOG")
panel:SetFrameLevel((cfg:GetFrameLevel() or 0) + 10)
panel:EnableMouse(true)
Expand Down Expand Up @@ -730,8 +723,13 @@ local function OpenBlessingPanel()
selector:SetPoint("TOPLEFT", 158, y)
cfg.blessingSelectors[i] = selector
end
panel.complement = MakeCheck(panel, L["Complement Nearby Blessings"],
function() return db.blessingComplement end, X.SetBlessingComplement)
panel.complement:SetPoint("TOPLEFT", 18, -321)
Tip(panel.complement, L["Complement Nearby Blessings"],
L["Offer a different known blessing outside your group if another Paladin already provides your preferred blessing. Explicit rules still take precedence."])
local hint = panel:CreateFontString(nil, "OVERLAY", "GameFontDisableSmall")
hint:SetPoint("TOPLEFT", 22, -330)
hint:SetPoint("TOPLEFT", 22, -355)
hint:SetWidth(442)
hint:SetJustifyH("LEFT")
hint:SetText(L["An active group blessing plan takes precedence."])
Expand Down Expand Up @@ -2897,7 +2895,6 @@ local function BuildConfig()
v = math.floor(v + 0.5)
db.idleFade = v
fadeValue:SetText(v .. "%")
X.curAlpha = nil
end, L["Idle fade (mouse away)"], function() return cfg.fadeValue:GetText() end)

local scaleLabel = look:CreateFontString(nil, "OVERLAY", "GameFontHighlight")
Expand Down Expand Up @@ -2944,7 +2941,7 @@ local function BuildConfig()

cfg.twoColCheck = MakeCheck(look, L["Two columns when the list is long"],
function() return db.twoCol end,
function(v) db.twoCol = v; X.cols = nil; Refresh() end)
function(v) db.twoCol = v; Refresh() end)
cfg.twoColCheck:SetPoint("TOPLEFT", 10, -396)

cfg.wizardBtn = MakeButton(look, "Run the setup wizard", 150, function()
Expand Down Expand Up @@ -3119,14 +3116,14 @@ local function BuildConfig()
OpenKeybinds()
end)
setKey:SetPoint("TOPLEFT", 14, -288)
local makeMacro = MakeButton(alerts, "Create macro", 120, function() MakeMacro(false) end)
local makeMacro = MakeButton(alerts, "Create macro", 120, function() MakeMacro() end)
makeMacro:SetPoint("LEFT", setKey, "RIGHT", 10, 0)

local hint = alerts:CreateFontString(nil, "OVERLAY", "GameFontDisableSmall")
hint:SetPoint("TOPLEFT", 14, -316)
hint:SetWidth(420)
hint:SetJustifyH("LEFT")
hint:SetText("Cast next buff targets the first player in the list. Doesn't fire in combat.")
hint:SetText(L["Cast next buff works with a keyboard or controller and does not fire in combat."])

------------------------------------------------------------------
-- Tab: Buffs
Expand Down Expand Up @@ -3995,6 +3992,7 @@ RefreshConfig = function()
if cfg.blessingPanel and cfg.blessingPanel:IsShown() then
if X.HasKnownBlessings() then
for _, selector in ipairs(cfg.blessingSelectors) do selector:Update() end
cfg.blessingPanel.complement:Update()
else
cfg.blessingPanel:Hide()
end
Expand Down
38 changes: 14 additions & 24 deletions BuffRadar/Coordination.lua
Original file line number Diff line number Diff line change
@@ -1,28 +1,18 @@
-- BuffRadar - Coordination: cast sync between BuffRadar users (1.5.0),
-- caster coordination (1.15.26), chat buff requests, per-buff context
-- checks and the join digest.
-- Loaded after BuffRadar.lua through the .toc. This is file-split Slice E
-- (1.15.34): the code below moved verbatim from BuffRadar.lua and reaches
-- that file's locals through X.coordAPI, which BuffRadar.lua fills in
-- before this file loads. The settings table arrives through X.dbSinks
-- once it exists; the two counters the main file reassigns (list length,
-- whether any buff is known) are read through accessors.
-- BuffRadar - cast sync, assignments, chat requests and group context.
-- Copyright (C) 2026 Malikor. GPLv3 or later.

local _, NS = ...
local X = NS and NS.X
if not X or not X.coordAPI then return end
local A = X.coordAPI
local _, ns = ...
local X = ns.X
local core = X.Core

local db = X.GetDB and X.GetDB() -- nil until ADDON_LOADED; X.dbSinks updates it
X.dbSinks = X.dbSinks or {}
X.dbSinks[#X.dbSinks + 1] = function(value) db = value end
local db
X.OnDBLoaded(function(value) db = value end)

local L, Print, PlayAlert, QueueRefresh = A.L, A.Print, A.PlayAlert, A.QueueRefresh
local Ignore, Readable, IsOn = A.Ignore, A.Readable, A.IsOn
local InRaid, InGroup, InInstanceNow = A.InRaid, A.InGroup, A.InInstanceNow
local BLESSINGS, BUFF_DEFS, CLASSIC_FEATURES = A.BLESSINGS, A.BUFF_DEFS, A.CLASSIC_FEATURES
local RAID, PARTY, myBuffs, entries = A.RAID, A.PARTY, A.myBuffs, A.entries
local L, Print, PlayAlert, QueueRefresh = X.L, X.Print, core.PlayAlert, core.QueueRefresh
local Ignore, Readable, IsOn = X.Ignore, X.Readable, core.IsOn
local InRaid, InGroup, InInstanceNow = X.InRaid, X.InGroup, core.InInstance
local BLESSINGS, BUFF_DEFS, CLASSIC_FEATURES = X.BLESSINGS, X.BUFF_DEFS, X.classic
local RAID, PARTY, myBuffs, entries = core.RAID, core.PARTY, core.Buffs, core.Entries
local pairs, ipairs, next, type, pcall = pairs, ipairs, next, type, pcall
local tonumber = tonumber
local math_floor, math_max = math.floor, math.max
Expand Down Expand Up @@ -1042,7 +1032,7 @@ function X.OnChatAsk(text, author)
if not text:lower():find("buff", 1, true) then return end
local short = author:match("^[^%-]+") or author
local ka, ks = Ignore.Key(author), Ignore.Key(short)
for i = 1, A.nEntries() do
for i = 1, core.EntryCount() do
local e = entries[i]
if e and (Ignore.Key(e.fullName or "") == ka or Ignore.Key(e.sortName or "") == ks) then
if (not X.asked[e.guid] or GetTime() - X.asked[e.guid] > 30)
Expand Down Expand Up @@ -1096,7 +1086,7 @@ function X.InstanceCheck()
if not db then return end
local ctx = X.Context()
local inside = ctx == "dungeon" or ctx == "raid" or ctx == "pvp"
if inside and not X.wasInside and db.enterFlash and InGroup() and A.hasAnyBuff()
if inside and not X.wasInside and db.enterFlash and InGroup() and core.HasAnyBuff()
and not X.PlayerSuspended() then
local report = X.GroupBuffReport()
local people = #report.people
Expand Down Expand Up @@ -1131,7 +1121,7 @@ function X.OnRoster()
X.PruneAssignmentRoleOverrides()
X.PruneBlockerUndo()
if db then X.SendCover() end -- roster changes refresh a live cover (1.7.0)
if X.inGroupPrev == false and g and db and db.joinDigest and A.hasAnyBuff() then
if X.inGroupPrev == false and g and db and db.joinDigest and core.HasAnyBuff() then
if C_Timer and C_Timer.After then
C_Timer.After(1.5, function() X.JoinDigest("join") end)
else
Expand Down
14 changes: 7 additions & 7 deletions BuffRadar/Data.lua
Original file line number Diff line number Diff line change
@@ -1,13 +1,10 @@
-- BuffRadar - Data: buff tables, class sets, blessings, presets and themes.
-- Loaded FIRST through the .toc; everything lives on the shared namespace
-- table X so BuffRadar.lua (loaded next) can alias what it needs without
-- spending its own main-chunk locals (Lua 5.1 caps them at 200).
-- Initializes the private namespace before settings and core load.
-- Copyright (C) 2026 Malikor. GPLv3 or later.

local _, NS = ...
NS = NS or {}
local X = NS.X or {}
NS.X = X
local _, ns = ...
local X = {}
ns.X = X

-- Edition, picked at load from the client's interface version: the
-- Forever client reports 16001, retail 120105 and up. One source serves
Expand All @@ -23,6 +20,9 @@ do
end
X.classic = CLASSIC_FEATURES

X.friendlyPlateCVars = { "nameplateShowFriendlyPlayers", "nameplateShowFriends" }
X.friendlyPlateNamesCVar = "nameplateShowOnlyNameForFriendlyPlayerUnits"

-- Forever group spells consume one reagent per cast. The spellbook rank ID
-- selects the item, because the first ranks of two spells use cheaper items.
X.groupReagents = {
Expand Down
61 changes: 42 additions & 19 deletions BuffRadar/Extras.lua
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,16 @@ local function UpdateNearbyNameplates()
nearby.lastNameplates = enabled
local status = enabled == true and L["On"] or enabled == false and L["Off"] or L["Unknown"]
nearby.nameplates:SetText(string.format(L["Friendly nameplates: %s"], status))
nearby.enablePlates:SetShown(enabled == false)
nearby.togglePlates:SetText(L[enabled and "Disable Friendly Nameplates" or "Enable Friendly Nameplates"])
nearby.togglePlates:SetShown(enabled ~= nil)
local namesOnly = X.ReadBooleanCVar(X.friendlyPlateNamesCVar)
nearby.plateStyle:SetText(L[namesOnly and "Show Friendly Health Bars" or "Show Friendly Names Only"])
nearby.plateStyle:SetShown(namesOnly ~= nil)
nearby.restorePlates:SetShown(next(X.GetDB().plateRestore) ~= nil)
end

function X.UpdateNearbyPlateControls()
if nearby and nearby:IsShown() then UpdateNearbyNameplates() end
end

function X.UpdateNearbyScanCount()
Expand Down Expand Up @@ -55,7 +64,7 @@ end

local function BuildNearby()
local f = CreateFrame("Frame", "BuffRadarNearbyDiagnostics", UIParent)
f:SetSize(450, 252)
f:SetSize(480, 298)
f:SetPoint("CENTER")
f:SetFrameStrata("DIALOG")
f:SetClampedToScreen(true)
Expand Down Expand Up @@ -88,9 +97,9 @@ local function BuildNearby()

local scroll = CreateFrame("ScrollFrame", "BuffRadarNearbyScroll", f, "UIPanelScrollFrameTemplate")
scroll:SetPoint("TOPLEFT", 14, -112)
scroll:SetPoint("BOTTOMRIGHT", -30, 76)
scroll:SetPoint("BOTTOMRIGHT", -30, 108)
local child = CreateFrame("Frame", nil, scroll)
child:SetSize(406, 1)
child:SetSize(436, 1)
scroll:SetScrollChild(child)
f.scroll, f.scrollChild = scroll, child
f.details = child:CreateFontString(nil, "OVERLAY", "GameFontHighlight")
Expand All @@ -99,20 +108,34 @@ local function BuildNearby()
f.details:SetJustifyH("LEFT")
f.details:SetJustifyV("TOP")
f.details:SetWordWrap(true)
f.message = Label("GameFontHighlightSmall", -182)

local enable = CreateFrame("Button", nil, f, "UIPanelButtonTemplate")
enable:SetSize(280, 22)
enable:SetPoint("BOTTOMLEFT", 14, 12)
enable:SetText(L["Enable Friendly Nameplates"])
enable:SetScript("OnClick", function()
if not f:IsShown() or X.PlayerSuspended() or InCombatLockdown() or X.FriendlyPlatesOn() ~= false then return end
local message
X.EnableFriendlyNameplates(function(line) message = line end)
UpdateNearbyNameplates()
f.message:SetText(message or "")
f.message = Label("GameFontHighlightSmall", -196)
f.message:SetWordWrap(true)
f.message:SetJustifyV("TOP")

local function PlateButton(width, point, x, y, chooseMode)
local btn = CreateFrame("Button", nil, f, "UIPanelButtonTemplate")
btn:SetSize(width, 22)
btn:SetPoint(point, x, y)
btn:SetScript("OnClick", function()
if not f:IsShown() or not btn:IsShown() or X.PlayerSuspended() or InCombatLockdown() then return end
local mode = chooseMode()
if not mode then return end
local message
X.ChangeFriendlyNameplates(mode, function(line) message = line end)
f.message:SetText(message or "")
end)
return btn
end
f.togglePlates = PlateButton(266, "BOTTOMLEFT", 14, 42, function()
local enabled = X.FriendlyPlatesOn()
if enabled ~= nil then return enabled and "off" or "on" end
end)
f.plateStyle = PlateButton(266, "BOTTOMLEFT", 14, 12, function()
local namesOnly = X.ReadBooleanCVar(X.friendlyPlateNamesCVar)
if namesOnly ~= nil then return namesOnly and "bars" or "names" end
end)
f.enablePlates = enable
f.restorePlates = PlateButton(176, "BOTTOMRIGHT", -14, 42, function() return "restore" end)
f.restorePlates:SetText(L["Restore Nameplates"])

local refresh = CreateFrame("Button", nil, f, "UIPanelButtonTemplate")
refresh:SetSize(110, 22)
Expand Down Expand Up @@ -268,7 +291,7 @@ function X.ApiCheck(export)
-- Readability tier: the presence table above cannot see a restricted
-- result, which is the failure that actually hides players from the list.
local unit, unitWhy = ProbeUnit()
local buffs = X.slashAPI and X.slashAPI.myBuffs
local buffs = X.Core.Buffs
local spell = (buffs and buffs[1] and buffs[1].name) or "Arcane Intellect"
out(string.format(" readability on %s (%s), spell %s:", unit, unitWhy, spell))
local PROBES = {
Expand Down Expand Up @@ -603,7 +626,7 @@ do
end

---------------------------------------------------------------------------
-- Slash registration (dispatched from BuffRadar.lua's HandleSlash)
-- Slash registration (dispatched by Slash.lua)
---------------------------------------------------------------------------
X.ext.apicheck = function(rest) X.ApiCheck(rest == "export") end
X.ext.ignorelist = function(rest)
Expand Down
Loading
Loading