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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
- `UnitFrames/Core/`: namespace/bootstrap, schema, AceDB configuration, theme, media, colours and text formats. Core Lua files receive `local _, ns = ...`; the public `UnitFrames` handle exposes that namespace to companion addons.
- `UnitFrames/Tracking/`: data-only DoT damage estimates (tracking ported from DoesItDie, MIT). `DotSpells` reads generated numeric metadata, never descriptions. `ns.DotTracker` runs only while `Acquire`d on the exact catalogue client build, checks player-known spell IDs, keys active DoTs by generated family and learns ticks per rank. It matches `UNIT_COMBAT` on target/focus, fires `DotsChanged(key)` and fills reused lists through `Breakdown`. In combat `UNIT_COMBAT` amounts are secret: those hits match on school and rhythm alone (never drop them, or every DoT looks resisted) and are tallied per spell; on `PLAYER_REGEN_ENABLED` the `C_DamageMeter` per-spell totals, minus the generated `directPoints` upfront hit, become weighted average ticks. Fights with unseen ticks, several combo-point sizes or a dominant upfront hit are not learned. Learned tick sizes and weights live in AceDB `global`.
- `tests/proof/atlases.lua` is generated by the library's `.wut/scripts/atlas_catalog.py --scan ... --output tests/proof/atlases.lua` (command in DEVELOPMENT.md) from Wago atlas exports for its pinned Forever build. Regenerate it after adding a `SetAtlas` call, so UI proof draws the atlas.
- `Tracking/DotCatalog.lua` is generated by `python3 -B scripts/spell_catalog.py` from checksum-verified Wago exports cached under ignored `examples/forever-spells/<build>/`. Only the manifest (`data/forever-spells/manifest.json`), generated Lua and small native-record fixtures are tracked. It must match the exact Forever UI-source build/commit the wow-ui-testing library pins (`.wut/clientdata/forever.json`) and the TOC interface; `--update` after a `.wut-version` bump that changes the build. `--fetch --check` populates a fresh cache and validates regeneration in CI. Ordinary tests use `--check-pin` and the small fixtures offline. The ignored `catalog.json` audits periodic candidates and exclusions; CI uploads it as an artifact. Channels are excluded. Runtime only accepts player-known spells. Combo builders, finishers, rank families and projectile flags are generated. Agony's uneven shape remains an explicit family-ID exception in `DotSpells`; baseline damage is unmodified client data until ticks are learned.
- `Tracking/DotCatalog.lua` is generated by `python3 -B scripts/spell_catalog.py` from checksum-verified Wago exports cached under ignored `examples/forever-spells/<build>/`. Only the manifest (`data/forever-spells/manifest.json`), generated Lua and small native-record fixtures are tracked. It must match the exact Forever UI-source build/commit the wow-ui-testing library pins (`.wut/clientdata/forever.json`) and the TOC interface; `--update` after a `.wut-version` bump that changes the build. `--fetch --check` populates a fresh cache and validates regeneration in CI. Ordinary tests use `--check-pin` and the small fixtures offline. The ignored `catalog.json` audits periodic candidates and exclusions; CI uploads it as an artifact. Channels are excluded. Runtime only accepts player-known spells. Combo builders, finishers, rank families and projectile flags are generated. Agony's uneven shape remains an explicit family-ID exception in `DotSpells`; baseline damage is unmodified client data until ticks are learned. The same script generates `Tracking/BuffCatalog.lua`: heal-over-time (`EffectAura` 8) and absorb (69) families whose skill-line ranks land on someone other than the caster, pet or master, grouped by the DoT family rule (class set, masks, school, aura), keyed by the lowest skill-line rank, with a `byId` lookup and the `SpellAuraVisibility` RaidInCombat set. Proc, external, defensive and raid-buff families come from `BUFF_EXTRAS`, which lists family roots only; ranks always come from the data.
- Pending DoT damage: `Components/PendingDamage.lua` is owned by Bar (`spec.pendingDamage`, health rows) like Overheal; the `pendingDamage` frame driver binds `UF_PendingDamage` (Elements.lua), and the health `PostUpdate` (`ufHealthHooks`) gives it the secret scale and current health.
- `UnitFrames/Components/`: reusable visual building blocks. Keep them independent of oUF bindings; their configuration and data APIs also serve previews. `UnitFrame` exposes rows and optional parts through `GetRow(key)`/`GetPart(key)` and the `Rows()`/`Parts()` iterators; add a part to `UnitFrame.PARTS` rather than adding per-part getters. Ready-check state lives in the `ReadyCheck` presenter (`GetReadyCheck()`), which also owns its settings schema.
- Classes (`Core/Class.lua`): configurable visuals extend `Component`, settings controls extend `Widget`, other stateful helpers extend `Object` (`Class:New(...)` calls `Init(...)`). Stateless calculations stay plain module tables of functions.
Expand Down
4 changes: 2 additions & 2 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ our frames (they skip without it; CI syncs it).

## Forever spell catalogue

`scripts/spell_catalog.py` compiles `UnitFrames/Tracking/DotCatalog.lua` from
Blizzard client tables exported by [Wago](https://wago.tools/db2). It uses the
`scripts/spell_catalog.py` compiles `UnitFrames/Tracking/DotCatalog.lua` and
`UnitFrames/Tracking/BuffCatalog.lua` from Blizzard client tables exported by [Wago](https://wago.tools/db2). It uses the
exact Forever build and UI-source commit the wow-ui-testing library pins
(`.wut/clientdata/forever.json`), and verifies the addon's TOC interface
against that build. Interface `16001` alone is insufficient to select spell
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ each change.
type colour (**Debuff glow**): a soft halo, or the animated proc flash from
Blizzard's action buttons.
- Filter buffs and debuffs by crowd control, big or external defensives,
important buffs, or your own heals over time.
important buffs, or your own heals and shields.
- Hide Blizzard's own player buff and debuff sections, each on its own toggle.
Changes wait until combat ends.
- Show crowd control and defensives over the portrait or on a frame edge, with
Expand Down
2 changes: 1 addition & 1 deletion THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ PolyForm license text is reproduced unchanged.
| oUF | UnitFrames | MIT; copyright (c) 2006–2026 Trond A Ekseth and (c) 2016–2026 Val Voronov, Adrian L Lange and Rainrider. Full text in `UnitFrames/Libs/oUF/LICENSE.txt`. |
| LibEditMode | UnitFrames | Custom upstream license; copyright (c) 2022–2026 Adrian L Lange. Full text in `UnitFrames/Libs/LibEditMode/LICENSE.txt`. |
| DoesItDie (ported DoT tracking logic) | UnitFrames (`Tracking/`) | MIT; copyright (c) 2026 Joe Greive. Full text in `UnitFrames/Licenses/DoesItDie-MIT.txt`. |
| Forever spell database exports | Generated metadata in `UnitFrames/Tracking/DotCatalog.lua`; manifest in `data/forever-spells/` and small records in `tests/fixtures/dot_source.json` | Blizzard client data exported by [Wago](https://wago.tools/db2), pinned to the Forever build and source commit in the manifest. Raw CSV snapshots and the full audit are ignored development inputs under `examples/forever-spells/` and are not shipped in addon ZIPs. |
| Forever spell database exports | Generated metadata in `UnitFrames/Tracking/DotCatalog.lua` and `UnitFrames/Tracking/BuffCatalog.lua`; manifest in `data/forever-spells/` and small records in `tests/fixtures/dot_source.json` | Blizzard client data exported by [Wago](https://wago.tools/db2), pinned to the Forever build and source commit in the manifest. Raw CSV snapshots and the full audit are ignored development inputs under `examples/forever-spells/` and are not shipped in addon ZIPs. |
| Roboto Condensed Light, Regular, Medium and Bold | UnitFrames_Media | SIL Open Font License 1.1; copyright 2011 The Roboto Project Authors. Full text in `UnitFrames_Media/Fonts/RobotoCondensed-OFL.txt`; notices also appear in the font metadata. |

Ace3's license allows embedding but prohibits standalone redistribution
Expand Down
14 changes: 10 additions & 4 deletions USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,10 @@ started**: turn it off in the AddOns list and nothing of it loads.
size, shown on the preview as you click.
3. **Add the extras**: castbars on your player, target and focus frames,
experience, combo points, and the standalone timer bars with global
cooldown and swing timer. **Save as a new profile** (on by default) puts
cooldown and swing timer. With ClickGrid loaded, the Healer look or a
druid, priest, paladin or shaman also gets **Heals on group frames**: your
own HoTs and shields on ClickGrid cells, outside the cell, in its corners
or in an aura bar. **Save as a new profile** (on by default) puts
the look into a new profile named after it and switches to it; your
previous profile is left untouched. Turn it off to replace the style of
the current profile instead. Frame positions always stay.
Expand Down Expand Up @@ -397,9 +400,12 @@ border by type** to use **Icon frame > Border colour** for every icon.
their timers; Animated previews cycle them. Samples include stacks, a
permanent buff, and all four debuff dispel types, using the saved aura style.

**Which** also offers category filters: **My heals over time** (your own
buffs flagged for raid frames in combat), **Big defensives**, **External
defensives**, **Important** buffs, and **Crowd control** debuffs.
**Which** also offers category filters: **My heals & shields** (your own heals
over time, shields and heal procs, every rank of each spell), **My raid-flagged
buffs** (your own buffs whose spell ID the client flags for raid frames in
combat; it misses some ranks of Rejuvenation, Regrowth and Renew and every shield), **Externals & defensives**
(anyone's, every rank), **Raid buffs of every class** (every rank), **Big defensives**, **External defensives**,
**Important** buffs, and **Crowd control** debuffs.

## Crowd control & defensives

Expand Down
34 changes: 26 additions & 8 deletions UnitFrames/Components/Auras.lua
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,14 @@ Auras.STACK_FIRST = {
{ "buffs", "Buffs" }, { "debuffs", "Debuffs" },
}

Auras.MY_HEALS, Auras.EXTERNALS, Auras.RAID_BUFFS = "MY_HEALS", "EXTERNALS", "RAID_BUFFS"

Auras.BUFF_FILTERS = {
{ "HELPFUL", "All buffs" }, { "HELPFUL|PLAYER", "Cast by me" }, { "HELPFUL|RAID", "Raid buffs" },
{ "HELPFUL|PLAYER|RAID_IN_COMBAT", "My heals over time" },
{ Auras.MY_HEALS, "My heals & shields" },
{ Auras.EXTERNALS, "Externals & defensives (anyone's, all ranks)" },
{ Auras.RAID_BUFFS, "Raid buffs of every class (all ranks)" },
{ "HELPFUL|PLAYER|RAID_IN_COMBAT", "My raid-flagged buffs (not all ranks, no shields)" },
{ "HELPFUL|BIG_DEFENSIVE", "Big defensives" }, { "HELPFUL|EXTERNAL_DEFENSIVE", "External defensives" },
{ "HELPFUL|IMPORTANT", "Important" },
}
Expand All @@ -50,6 +55,15 @@ Auras.SAMPLE_FILTER_FLAGS = {

local CLASSIFIED_FILTERS = { BIG_DEFENSIVE = true, EXTERNAL_DEFENSIVE = true, IMPORTANT = true }
local ALL_FILTERS = { buffs = "HELPFUL", debuffs = "HARMFUL" }
local CATALOG_FILTERS = {}
for name, set in pairs(ns.BuffSpells.SETS) do
CATALOG_FILTERS[name] = { filter = set.filter, spellIDs = function() return ns.BuffSpells.SetIDs(name) end }
end

function Auras.IncludeSpellIDs(filter)
local catalog = CATALOG_FILTERS[filter]
return catalog and catalog.spellIDs() or nil
end

function Auras.FilterSupported(filter)
if ns.Caps.auraClassification then return true end
Expand All @@ -60,6 +74,7 @@ function Auras.FilterSupported(filter)
end

function Auras.GroupFilter(kind, filter)
if CATALOG_FILTERS[filter] then return CATALOG_FILTERS[filter].filter end
return Auras.FilterSupported(filter) and filter or ALL_FILTERS[kind]
end

Expand Down Expand Up @@ -248,7 +263,9 @@ end

-- A group's native candidate filters (nil = none).
function Auras.CandidateFilters(group)
return group.maxDuration > 0 and { maxDuration = group.maxDuration } or nil
local include = Auras.IncludeSpellIDs(group.filter)
if group.maxDuration <= 0 and not include then return nil end
return { maxDuration = group.maxDuration > 0 and group.maxDuration or nil, includeSpellIDs = include }
end

-- Native setters that do engine work even for unchanged values: candidate
Expand All @@ -271,10 +288,10 @@ local function Applied(container, kind)
end

function Auras.ApplyGroupCandidates(container, kind, group)
local applied = Applied(container, kind)
if applied.maxDuration == group.maxDuration then return end
applied.maxDuration = group.maxDuration
container:SetAuraGroupCandidateFilters(kind, Auras.CandidateFilters(group))
local applied, candidates = Applied(container, kind), Auras.CandidateFilters(group)
if applied.hasCandidates and ns.Util.Equals(applied.candidates, candidates) then return end
applied.hasCandidates, applied.candidates = true, candidates
container:SetAuraGroupCandidateFilters(kind, candidates)
end

function Auras.ApplyGroupSort(container, kind, method, direction)
Expand Down Expand Up @@ -564,7 +581,8 @@ function Auras:ShowSample(values)
self:RenderSamples()
end

function Auras.MatchesSampleFilter(aura, filter, maxDuration)
function Auras.MatchesSampleFilter(aura, filter, maxDuration, includeSpellIDs)
if includeSpellIDs and not includeSpellIDs[aura.spellId] then return false end
for component in filter:gmatch("[^|]+") do
if component == "PLAYER" and aura.sourceUnit ~= "player" then return false end
local flag = Auras.SAMPLE_FILTER_FLAGS[component]
Expand All @@ -583,7 +601,7 @@ function Auras:RenderSamples()
if cfg.enabled then
for _, aura in ipairs(self:GetSampleOrder(kind)) do
if #elements >= self:GetSampleLimit(kind) then break end
if Auras.MatchesSampleFilter(aura, Auras.GroupFilter(kind, cfg.filter), cfg.maxDuration) then
if Auras.MatchesSampleFilter(aura, Auras.GroupFilter(kind, cfg.filter), cfg.maxDuration, Auras.IncludeSpellIDs(cfg.filter)) then
local index = #elements + 1
local button = container.ufButtons[index]
if not button then
Expand Down
Loading
Loading