Files
2026-10-19 10:36:44 +01:00

387 lines
39 KiB
Markdown

# pfUI Octo meters: design spec (roadmap phase 5)
Written 19 Oct 2026. Design only, no code. Target: 1.12.1 build 5875 (OctoWoW), Lua 5.0, pfUI `octo`
branch. Goal from the user: "They should tell you everything. all interupts all casts everything."
Replaces ShaguDPS and TWThreat. Credit ShaguDPS (parser approach); TWThreat code is not copied (no
licence), only its wire protocol is described (section 3).
How this was researched: feature lists of Details!, Recount and Skada come from their long-standing
public feature sets (web search for them returned little; no page enumerated the modes, so the lists
below are from knowledge of the addons and the Numeration / MiliUI pages found, and are the
reference for scope, not a quote). Data sources were read from this install: `ShaguDPS\parser.lua`,
`parser-vanilla.lua`, `Spy\SpyNampower.lua`, `OctoBG\CLAUDE.md`, `OctoBG\modules\Threat.lua`,
`TWThreat\TWThreat.lua`, and the exported names in `nampower.dll` (extracted with grep, checked).
The nampower EVENTS.md on gitea could not be fetched (sign-in page), so argument layouts are marked
**V** (verified in a file here) or **R** (recalled from EVENTS.md, check with a probe before coding).
Status words used below: **available** (data is there), **partial** (say what is missing),
**impossible** (not on 1.12).
---
## 1. What the retail meters show
### 1.1 Display modes
Details! (Tercio), grouped as its own menu does:
| Group | Modes |
|---|---|
| Damage | Damage Done, DPS, Damage Taken, Friendly Fire, Frags (kills), Enemies (damage done to / taken from each enemy), Voidzone damage, Damage Done by Spell (all sources), Damage Done by target |
| Healing | Healing Done, HPS, Overheal, Healing Taken, Healing Prevented, Absorbs ("Damage prevented"), Heal Enemy |
| Resources | Mana restored, Rage / Energy / other power generated |
| Utility ("Misc") | Interrupts, Dispels, Cooldowns used (defensive and raid), CC breaks, Resurrections, Deaths, Buff Uptime, Debuff Uptime, Spell casts ("Spell Cast" is in a plugin) |
| Plugins | Tiny Threat, Vanguard (tank view: tanks' debuffs and incoming), Encounter Details, Time Line, Chart Viewer, Advanced Death Logs, Streamer, Coach |
Recount: Damage Done, Damage Taken, Healing Done, Healing Taken, Overhealing, DPS, Deaths,
Dispels, Interrupts, CC Breakers, Resurrections, Threat, Activity (time spent in combat), Mana
Gained, Buffs gained, Debuffs gained, Friendly Fire, Avoidance (dodge / parry / block counts), Fight
(summary), "Damage done on <mob>" per mob, graphs in the detail window.
Skada: Damage, Damage Taken, Enemy Damage Done / Taken, Healing, Overhealing, Absorbs, Dispels,
Interrupts, Deaths, Buffs and Debuffs (uptime), Avoidance and Mitigation, CC Done, CC Breaks,
Threat, Resurrects, Power Gains, Activity, Casts, Friendly Fire, Fails (avoidable damage),
spell-school splits.
Numeration (found by search) adds a chronological Deathlog and "Damage Taken: Targets / Abilities".
### 1.2 Detail views (drill-down)
- Per-spell breakdown for any actor: total, % of total, hits, crits, misses, glancing, crushing,
blocked, resisted, absorbed, min / max / average, crit %, hit %, per-second, for DoT ticks vs direct.
- Per-target breakdown (who was hit, by how much) and the reverse (who hit this actor, with what).
- Spells shown per target and targets per spell (Skada "Shift-click"; Details! "Targets" tab).
- Avoidance tab (dodge / parry / block / miss / absorb counts and rates), Auras tab (uptime, applications),
compare two players side by side (Details!).
- Pets merged under the owner, with a pet sub-line; multi-pet "Pet: Name".
- Death log: last N events before death with timestamp, source, spell, amount, HP at the time,
heals in between, overkill; click a death to open it. Details! shows a mini HP graph.
### 1.3 Window UX
- Tabs / mode menu in the title bar (click title = pick mode, right-click = options).
- Segments: Current, Overall, previous fights (list, boss fights named), trash merged, auto-reset on
entering an instance with a prompt, "Remove segment", data kept after reload (saved variables).
- Multiple windows (Details! up to many, Recount one per mode), snapped together, each with its own
mode and segment, mirrored scale / alpha / bar texture / font.
- Bar: rank number, class icon, name, value, % and per-second; class colour; hover tooltip listing
top spells (Details! with Shift = targets, Ctrl = pets, Alt = percent only); click opens the drill-down;
right-click for options; scroll wheel; bar for "You" pinned when outside top N.
- Report to chat: Say / Party / Raid / Guild / Whisper / Officer / channel / "copy window text", with a
line-count box; report for a single player's spells.
- Title shows the segment name and combat time; collapse to title only; lock; auto-hide out of combat.
- Reset button with confirmation, sync of data between users (Recount "Network" / Details! raid damage
sync), export of a segment, minimap button.
---
## 2. Data sources on this client
### 2.1 The source toolbox
| Source | What it gives | Requirements / limits |
|---|---|---|
| **A. Combat-log chat events** `CHAT_MSG_COMBAT_*`, `CHAT_MSG_SPELL_*` | Localised strings, parsed with GlobalStrings patterns (`SPELLLOGSCHOOLOTHEROTHER` ...), names only (no GUIDs, no spell ids). ShaguDPS parses only damage and heals (`parser-vanilla.lua`, patterns above line 110). Many more GlobalStrings exist: `SPELLINTERRUPT*`, `DISPEL*`, `UNITDIES*`, `SPELLRESIST*`, `VS*` (dodge / parry / block / absorb), `AURAADDED*`, `AURAREMOVED*`, `SPELLCASTGO*` / `SPELLPERFORMGO*`, `SPELLLOGABSORB*`, `HEALEDCRIT*` | Range-limited: the client only emits log lines for events within the combat-log range CVars (`CombatLogRangeParty` / `Friendly` / `Hostile` / `Creature`, default 50 yd, max is server-/client-clamped; OctoBG's notes mention the range CVars but never measured their ceiling). Raid members out of range are silent. Names are ambiguous for same-name players / pets. |
| **B. nampower events** (installed, v in `nampower.dll`) | GUIDs, spell ids, exact numbers, for the player (`*_SELF`) and everyone else the client sees (`*_OTHER`). Names found in the DLL: `AUTO_ATTACK_SELF/OTHER`, `SPELL_START_SELF/OTHER`, `SPELL_GO_SELF/OTHER`, `SPELL_FAILED_SELF/OTHER`, `SPELL_DELAYED_SELF/OTHER`, `SPELL_DAMAGE_EVENT_SELF/OTHER`, `SPELL_MISS_SELF/OTHER`, `SPELL_HEAL_BY_SELF/OTHER`, `SPELL_HEAL_ON_SELF`, `SPELL_ENERGIZE_BY_SELF/OTHER`, `SPELL_ENERGIZE_ON_SELF`, `SPELL_DISPEL_BY_SELF/OTHER`, `AURA_CAST_ON_SELF/OTHER`, `BUFF_ADDED/REMOVED_SELF/OTHER`, `DEBUFF_ADDED/REMOVED_SELF/OTHER`, `BUFF/DEBUFF_UPDATE_DURATION_SELF`, `DAMAGE_SHIELD_SELF/OTHER`, `ENVIRONMENTAL_DMG_SELF/OTHER`, `UNIT_DIED`, `SPELL_CAST_EVENT` (your own cast attempts), `UNIT_AURA_GUID` / `UNIT_HEALTH_GUID` / `UNIT_COMBAT_GUID` and friends (GUID-keyed unit events). Functions: `GetSpellRecField(id, "name")`, `GetSpellNameAndRankForId`, `GetSpellIconTexture`, `GetUnitField(unit, "aura")`, `GetUnitGUID`, `GetCastInfo`. | CVars must be 1: `NP_EnableSpellStartEvents`, `NP_EnableSpellGoEvents`, `NP_EnableAutoAttackEvents`, `NP_EnableSpellHealEvents`, `NP_EnableSpellEnergizeEvents`, `NP_EnableAuraCastEvents` (Spy sets them; OctoBG never did). `*_OTHER` events are range-limited by the server's visibility (the client must have the unit in its object list); whether they cover party members beyond 50 yd and whether `*_OTHER` includes the player's own party/pets is **not verified in game** (AnySCT marks it unverified too). |
| **C. SuperWoW** | `UNIT_CASTEVENT` (caster GUID, target GUID, kind START / CAST / FAIL / CHANNEL / MAINHAND / OFFHAND, spell id, duration), GUID as the second return of `UnitExists`, `SpellInfo(id)`, GUID-as-unit-token in `Unit*` calls, `RAW_COMBATLOG` (log text with GUIDs; **R**, check it exists in this build), pet owner appended to names as `Name (Owner)` (ShaguDPS handles this in `ScanName`). | Installed. pfUI already wraps it (`modules\superwow.lua`). Use as GUID/spell-id fallback and as the cast-start source when nampower casts are off. |
| **D. ClassicAPI** | `C_UnitAuras.GetUnitAuras(unit)` with expiration time and source GUID, `C_Spell.GetSpellTexture`, `C_NamePlate`, `C_LossOfControl` (see `docs/API.md` of brues-code/ClassicAPI; OctoBG notes list what is verified). | Optional (detect `C_UnitAuras`). |
| **E. UNIT_AURA / aura APIs** | `UnitBuff` / `UnitDebuff` (32 buffs, 16 debuffs visible); nampower `GetUnitField(unit, "aura")` = 48 raw slots with spell ids. | Needs a unit token or GUID the client knows; no caster info except via D or aura-cast events. |
| **F. Plain game APIs** | `UnitAffectingCombat`, `UnitHealth/Max` for group units, `GetNumRaidMembers`, `UnitClass`, `GetTime`, `GetRealZoneText`, `IsInInstance` (return values on this server unverified), `GetInstanceInfo` absent in 1.12 | |
| **G. Addon messages** | `SendAddonMessage` to RAID / PARTY: threat protocol, optional meter sync between pfUI Octo users | Server may rate limit; OctoBG throttles at 500 B/s. |
Rule of thumb for the design: **nampower events are the primary feed** (GUIDs, spell ids, no string parsing, no locale),
**combat-log strings are the fallback** (client without nampower, and the only source for things nampower
has no event for, such as interrupts and absorb amounts), SuperWoW fills gaps. Everything funnels
through one `Feed()` that takes `(time, kind, srcGuid|name, dstGuid|name, spellId|name, amount, flags)`
so sources can be swapped without touching the data model (section 4).
### 2.2 Feature by feature
Argument layouts: **V** from `Spy\SpyNampower.lua` / `OctoBG\CLAUDE.md`, **R** recalled. Where it says
"log string" the GlobalString name is the one to take from `GlobalStrings.lua` of the client (patch-3).
| # | Feature | Verdict | Data source and what is missing |
|---|---|---|---|
| 1 | **Damage done** (melee, spells, DoTs, shields, pets) | **available** | nampower: `AUTO_ATTACK_*` (attacker, target, dmg, hitInfo, victimState, parts, blocked, absorb, resist; **V** OctoBG), `SPELL_DAMAGE_EVENT_*` (target, caster, spellId, amount, "absorb,block,resist", hitInfo, school, "eff1,eff2,eff3,auraType"; **V**; auraType 3 / 53 / 89 = periodic), `DAMAGE_SHIELD_*` (shield owner, attacker, damage; **V**), `ENVIRONMENTAL_DMG_*` (unit, type, damage; **V**). Fallback: `CHAT_MSG_COMBAT_*_HITS`, `CHAT_MSG_SPELL_*_DAMAGE`, `PERIODIC_*_DAMAGE` as in ShaguDPS. Pets: map pet GUID to owner via `UnitName("pet")`/GUID tokens (`raidpetN`), SuperWoW `Name (Owner)` suffix. |
| 2 | **DPS** (per second) | **available** | Computed: value / combat time. Two denominators like Details!: raid time (segment length) and **activity time** (item 14). |
| 3 | **Damage taken**, by source, by spell | **available** | Same events as 1, aggregated by target. Includes mitigated parts: `blocked`, `absorb`, `resist` fields. |
| 4 | **Friendly fire** | **available** | Damage events where source and target are both group members (GUID in roster). Needs the roster map `guid -> player`. |
| 5 | **Enemies** (damage done to / from each mob, "Enemy damage taken") | **available** | Aggregate by target GUID/name (mob). Mob names from `UnitName(guid)` (SuperWoW GUID tokens) else from log strings. Voidzone damage = damage from a creature source whose name matches a list: **partial** (no list shipped; user-curated). |
| 6 | **Damage done by spell (all sources)**, **damage done on <target>** | **available** | Pure aggregation of the spell tables. |
| 7 | **Healing done / HPS / healing taken** | **available** | nampower `SPELL_HEAL_BY_*` (target, caster, spellId, amount, crit, periodic; needs `NP_EnableSpellHealEvents`; **V** layout from OctoBG; for self also `SPELL_HEAL_ON_SELF`). Fallback strings `HEALED*`, `PERIODICAURAHEAL*` (ShaguDPS). |
| 8 | **Overhealing / effective healing** | **partial** | The heal event's `amount` is, as far as known, the gross amount (not verified; OctoBG's overheal estimate "UNIT_HEALTH vs heal event order" is also unverified). Effective = min(amount, maxHP - HP before heal), HP before the heal from the last `UNIT_HEALTH_GUID` value (or `UnitHealth(unit)` for group tokens). Wrong when the health update arrives before the heal event. ShaguDPS does the same with current HP, which is less accurate. Needs an in-game probe: print HP before/after and `amount` on a few heals to learn the order, then pick the formula. Works only for units the client sees with health (group members; not far-away raid targets). |
| 9 | **Absorbs** (damage prevented by shields: PW:S, Ice Barrier, Mana Shield ...) | **partial** | The *victim side* is exact: the "absorb" number in damage events (`SPELL_DAMAGE_EVENT` string field, `AUTO_ATTACK` absorb field) and `SPELL_MISS` missInfo 10 (full absorb). *Attributing it to the shield's caster* needs the active shield on the victim: `AURA_CAST_ON_*` (spellId, caster, target; needs `NP_EnableAuraCastEvents`; **V**) gives who put which absorb spell on whom; the absorbed amount is credited to the caster of the newest absorb aura on that victim that is in a hand-kept absorb-spell list. Not exact with stacked shields or when the aura was cast out of range. Remaining shield amount: **impossible** (not exposed by the 1.12 client). |
| 10 | **Heal prevented / heal on enemy** | **impossible / niche** | Mortal Strike and Wound Poison reduction is not reported as a number. Healing on enemy units is just a heal event with an enemy target, available but low value; skip. |
| 11 | **Resources** (mana restored, rage / energy generated) | **available** | `SPELL_ENERGIZE_BY_*` (target, caster, spellId, powerType, amount, periodic; needs `NP_EnableSpellEnergizeEvents`; **V**). Fallback `POWERGAIN*` strings. Auto-attack rage is not an event: **partial** (UnitMana delta for the player only). |
| 12 | **Interrupts** (who kicked what, with what) | **available** (strings) / **partial** (events) | There is **no `SPELL_INTERRUPT` event** in nampower (checked in `nampower.dll`). Reliable source: the combat-log line `SPELLINTERRUPTSELFOTHER` / `SPELLINTERRUPTOTHEROTHER` / `SPELLINTERRUPTOTHERSELF` ("X interrupts Y's Z"), names only; OctoBG's notes confirm `SPELLINTERRUPTSELFOTHER` exists in this client's GlobalStrings. Event-based cross check: kick spell id seen in `SPELL_GO_*` / `UNIT_CASTEVENT` from a known interrupt spell list (Pummel, Kick, Shield Bash, Earth Shock, Counterspell, Feral Charge..., hand-kept table) and `SPELL_FAILED_OTHER` / `UNIT_CASTEVENT` FAIL on the victim within ~150 ms. Gives GUIDs and spell ids; needs the table. Build both and use the string as the truth, events as enrichment (victim's interrupted spell id). The interrupted spell **name** is in the string. Locked-out school/duration: not reported. |
| 13 | **Dispels / purges** (what was removed, by whom, from whom) | **available** | nampower `SPELL_DISPEL_BY_*` (caster, target, spellId; **V** layout from Spy). The *removed aura's* name: `DISPELLED*` / `AURAREMOVED` log lines (`DISPELLEDSELFOTHER`, `DISPELLEDOTHEROTHER`, `DISPELLEDOTHERSELF` ...), and the preceding `BUFF/DEBUFF_REMOVED_*` at the same timestamp. Failed dispels: `SPELLRESISTED` / `SPELL_MISS` with dispel spell ids (**partial**: only via the resist line). |
| 14 | **Activity time** | **available** | Derived: union of intervals around each action by the actor (gap > 5 s ends an interval, same rule as ShaguDPS `_ctime`, plus cast durations from `SPELL_START/GO` for channelers). |
| 15 | **Casts per player ("all casts")** | **available** | `SPELL_GO_*` / `SPELL_START_*` (nampower; **V** arg2 = spellId, arg3 = casterGuid for `_OTHER` events; the target GUID and flags are further args, **R**), `SPELL_CAST_EVENT` for your own presses, SuperWoW `UNIT_CASTEVENT` as the alternate feed (includes channel starts and swing timers). Counts: casts started, finished (GO), failed (`SPELL_FAILED_*`), interrupted (item 12), delayed (`SPELL_DELAYED_*`), cast time lost. Instants appear as GO only. Range: whatever the client's object list holds, which includes enemy casters far beyond combat-log range (OctoBG sees enemies at 350+ yd) - a real advantage over the log. Filter to group + chosen enemies so it does not drown in trash casts. Spell names/icons via `GetSpellRecField(id, "name")`, `GetSpellIconTexture`. |
| 16 | **Hit / crit / miss / glancing / crushing / block stats per spell** | **available** | Autos: `hitInfo` 0x80 crit, 0x4000 glancing, 0x8000 crushing, 0x10 miss; `victimState` 2 dodge, 3 parry, 5 block, 6 evade, 7 immune, 8 deflect (**V**, OctoBG). Spells: `hitInfo` bit 0x2 crit (**V**), `SPELL_MISS_*` missInfo 1 miss, 2 resist, 3 dodge, 4 parry, 5 block, 6 evade, 7/8 immune, 9 deflect, 10 absorb, 11 reflect (**V**, Spy's table). Partial resists = the resist field. min / max / average from the amounts. Fallback: the "crits" and "resisted" strings. |
| 17 | **Avoidance (dodge / parry / block / miss counts for tanks)** | **available** | The two tables above with the group member as victim. |
| 18 | **Deaths + death log** | **available** (deaths) / **partial** (HP trail) | Death moment: `UNIT_DIED` (guid, from the server's death record, real deaths not Feign; **V**), fallback `UNITDIESSELF`/`UNITDIESOTHER` strings and `PLAYER_DEAD`. Death log = per-player ring buffer of the last ~10 s / 15 events (damage taken, heals received, aura changes) stamped with the time; HP at each step is **partial**: group members' HP from `UNIT_HEALTH_GUID` or `UnitHealth(token)`; raid members beyond the object list have none. Overkill = last hit minus HP just before. Killing blow = last damage event. Needs the buffer to run for **all** group members all the time (cheap, a ring of 15 small tables per player). |
| 19 | **Resurrections** | **available** | `SPELL_GO` of resurrection ids (hand-kept: Resurrection, Redemption, Ancestral Spirit, Rebirth, Soulstone Resurrection) plus a `UNIT_DIED` -> alive transition; fallback `RESURRECT*` strings. |
| 20 | **CC done** (what was crowd-controlled, by whom, how long) | **partial** | `AURA_CAST_ON_OTHER` (spellId, caster, target) + `DEBUFF_ADDED_OTHER` / `DEBUFF_REMOVED_OTHER` (guid, luaSlot, spellId, stacks...; **V**) for spell ids in a hand-kept CC table (Polymorph, Sap, Fear, Hibernate, Hammer of Justice, Shackle, Banish, Seduction ...). Duration = removal time minus add time. Needs the table (OctoBG's `data\` has DR / CC style tables to start from: `OctoBG.CDData`). Breaks of heavy stuns on bosses: skip. |
| 21 | **CC breaks** (who broke it, with what) | **partial** | The game never says who broke a CC. Heuristic: the CC aura on target T is removed (`DEBUFF_REMOVED_*`) within ~200 ms of a damage event on T (`SPELL_DAMAGE_EVENT` / `AUTO_ATTACK`); credit the damage source (retail Details! does the same with its own combat log). False positives when the CC just ended. Mark "probable". |
| 22 | **Buff uptime / debuff uptime** (your debuffs on bosses, raid buffs, flasks) | **available** (own units) / **partial** (everyone) | Buffs: `BUFF_ADDED/REMOVED_*` (guid, luaSlot, spellId, stacks, level, rawSlot, state; **V**) for any unit in the object list; `UNIT_AURA_GUID`; `GetUnitField(unit, "aura")` snapshot at pull (48 slots) to catch auras already up; `UnitBuff` for group tokens. Debuff uptime on a boss: `DEBUFF_ADDED/REMOVED_*` on the boss GUID. Caster attribution (whose Sunder Armor): `AURA_CAST_ON_*` or ClassicAPI `sourceGUID`. Limit: the 16 visible debuff slots on the target (the server can have more than 16 on a boss and the extras are hidden, so counts for the 17th+ debuff are missing). |
| 23 | **Cooldowns used** | **available** | `SPELL_GO_*` of ids in a defensive / raid CD table (Shield Wall, Last Stand, Lay on Hands, Power Infusion ...). Table shared with OctoBG cooldown data. |
| 24 | **Per-spell and per-target breakdowns** | **available** | Pure data model (section 4). |
| 25 | **Segments** (current, overall, per fight, boss, trash merge) | **available** | `PLAYER_REGEN_DISABLED/ENABLED` plus group combat check (ShaguDPS `combat()` in `parser.lua` polls `UnitAffectingCombat` on all group units every second; keep that). Boss detection: `UnitClassification(unit)=="worldboss"`/skull level -1 on the first hostile target, plus kill record by `UNIT_DIED` of a boss GUID (**partial**: 1.12 has no `ENCOUNTER_START`, there is no boss list; use a user-extendable list). Segment name = first enemy with most damage taken. |
| 26 | **Reports to chat** | **available** | `SendChatMessage` to say / party / raid / guild / whisper / channel; one line per row, max ~255 chars, throttle 1 line/0.1 s (pfUI/OctoBG `U.SendBG` pattern). |
| 27 | **Window UX** (multiple windows, tabs, tooltips, drill-down) | **available** | Pure UI. 1.12 constraints from OctoBG notes: no `GetStringHeight`, SetMovable windows, frame levels explicit, `OnUpdate` throttling. |
| 28 | **Saved fights / history after reload** | **available** | SavedVariables. Keep last ~15 segments compact (numbers only), purge detail tables above a size. |
| 29 | **Sync between users** (Recount network, Details! raid sync) | **partial** | `SendAddonMessage` works (OctoBG Spy channel is proven for BG; RAID untested for this). Only needed for range gaps; **not in v1**. |
| 30 | **Threat** | **partial** (server must answer) | Section 3. |
| 31 | **Healing received / taken from healers** | **available** | Aggregation of item 7 by target. |
| 32 | **Time line / charts (DPS over time)** | **available** | Store one bucket per second per actor for the active segment only (damage, healing); charts are UI. Later release. |
| 33 | **Avoidable damage ("fails")** | **partial** | Needs a boss-ability list; the user enters spell ids. Later. |
| 34 | **Item usage (consumables, flasks), mana potion / trinket use** | **available** | `SPELL_GO` with item id (arg1 = itemId on cast events, **R**) - low priority. |
| 35 | **Spell power / stats snapshots at cast time (Details! "Spell Details")** | **impossible** for others | Only your own stats via `GetSpellPower` / paperdoll; no inspect of everyone's live stats. |
| 36 | **Absorb remaining / shield value, mitigation after armour** | **impossible** | Client does not expose it. |
| 37 | **Combat log of players out of range, beyond the 50 yd range** | **partial** | nampower `*_OTHER` events reach as far as the object list; strings do not. Raise range CVars if the client allows (test: `/script SetCVar("CombatLogRangeParty",200)`; ceiling unverified). |
| 38 | **Mana / health graphs of every raider** | **partial** | `UNIT_HEALTH_GUID`, `UNIT_MANA_GUID` for GUIDs in the object list; UnitHealth for tokens. |
### 2.3 Combat-log range limits (what to tell the user)
- Strings: only within the combat-log range CVars (default 50 yd). Players farther away vanish from
the log. Pets and enemies are subject to the Hostile / Creature CVars. The addon should state it in
its options: "data from players further away than the combat-log range is missing" and offer a probe
that tries to raise the CVars (and reports what stuck).
- nampower events: the client generates them for units in its object list (server visibility radius,
OctoBG measured 350-420 yd for players in BGs). Range for friendly raid members in a 40-man is the
same list, so it should be better than the log - **verify in a raid**: compare `AUTO_ATTACK_OTHER`
counts with the log lines for a player standing 80 yd away.
- SuperWoW `UNIT_CASTEVENT` follows the same visibility.
- Double counting: if both a string and a nampower event are processed, the same hit is counted twice.
Decide per session which feed is active (nampower present and the CVars read back as 1 => events
only; otherwise strings only). Never both for damage / heal / miss. Interrupt strings and death strings
are the exception (supplement events).
---
## 3. Threat
### 3.1 The server protocol (from `TWThreat\TWThreat.lua` and `OctoBG\modules\Threat.lua`)
Described in words; no TWThreat code is copied. The server (Turtle-WoW lineage, **not verified on
OctoWoW**: TWThreat is disabled on the user's characters and has never run, and OctoBG's Threat module
has no recorded successful answer yet) answers addon messages for threat:
1. **Request.** The client sends an addon message with prefix `TWT_UDTSv4` and text `limit=N` over
`RAID` (when in a raid) or `PARTY` (in a party). `N` = how many players the server should list
(TWThreat sends visible bars minus one, OctoBG sends 10). A variant with prefix `TWT_UDTSv4_TM`
additionally asks for the tank-mode tail (below). The server evaluates it for the player's
**current target**, so a target switch changes the answer; a reply for a non-hostile or
out-of-combat target is empty.
2. **Cadence.** TWThreat asks every 0.5 s while any of its features is on, the player is in a group
and the target is in combat. OctoBG does the same and skips a request for 0.45 s after any answer
(so a second addon's answer feeds both). That is the protocol's polling rate; there is no push.
Group required: alone the server sends nothing.
3. **Reply.** A `CHAT_MSG_ADDON` event; the payload text (`arg2`, not `arg1`, which is the prefix field)
contains the marker `TWTv4=` followed by entries separated by `;`, each entry
`name:tank:threat:perc:melee` (more fields may follow; TWThreat passes a sixth through when relaying):
- `name` - player name (pets appear as their own name, the server decides),
- `tank` - `1` for the player who currently holds aggro, else `0`,
- `threat` - raw threat value (integer; can be negative in theory, OctoBG's pattern allows `-`),
- `perc` - the player's threat as a percentage of the tank's (the server computes it; OctoBG treats it as
"percent of the holder", and takes 100 for the holder),
- `melee` - `1` if the player is in melee range of the mob (decides 110 % vs 130 % to pull).
4. **Tank-mode tail.** If the message contains `#` followed by `TMTv1=`, the part after `#` is a second
record list `creature:guid:name:perc` joined by `;`: for each mob that the player's group is fighting,
the mob's name, its GUID (kept as a string), who it targets, and the player's threat percent on it.
Used for the "tank view": which of many mobs are on you or about to leave you. The server only
includes this in `_TM` mode. OctoBG currently drops it.
5. **Derived values (client side).**
- *Pull-aggro line*: holder's threat x 1.1 if you are in melee, x 1.3 if ranged (the standard classic
rule; both addons use it). TWThreat shows this as an extra row "-Pull Aggro at-".
- *TPS*: threat per second = averaged delta of the player's threat values over the last 10 s (the
client keeps `time -> threat` history from each reply; TWThreat uses 1 s buckets from `time()`).
- GUID repair: mob GUIDs come as the **low part only** from some server messages; TWThreat maps those
low ids back to full GUIDs through SuperWoW's `UNIT_MODEL_CHANGED` event. Needed only for tank mode.
6. **Failure handling.** If the server never answers: stop after N tries (OctoBG: 20) and show
"this server sent no threat data" until the next zone change. The meter must say so plainly in its
UI, because the TWT protocol may not exist on OctoWoW.
### 3.2 What a "Tiny Threat" style set of views could show
Details!'s Tiny Threat plugin: a small bar list for the current target with your threat, the tank's,
and the gap; colours by danger; "pull aggro" marker. Using only the reply above:
| View | Data | Notes |
|---|---|---|
| Threat list (bars, top N) | Name, class colour, raw threat, % of tank, TPS | Rows = reply entries sorted by `threat`; "You" pinned |
| Aggro line | Pull-aggro threshold row at 110 / 130 % of the holder | Needs the melee flag from the reply |
| Own gauge | Your threat as % of the pull line, big number, colour ramp | Same as OctoBG's label, but in the meter window |
| Danger alert | Flash / sound when above X % of pull line, once when you pull | Reuse OctoBG's thresholds idea (cap by `ref`-th player) |
| Tank view | Top 3 mobs by threat %, who they target, "loose mob" warning | Needs the `_TM` tail |
| Threat on target frame | % text on target frame/nameplate (pfUI nameplates already colour by aggro state) | Not from this server data alone: nameplate colours come from pfUI's own logic |
| Threat history chart | Your threat and the tank's over the last 30 s | From stored replies; a line chart in the window |
| Per-fight threat summary | End-of-fight peak threat / TPS per player | Store the last reply of each target per segment |
| Threat per mob | Tab per target GUID (current, focus, mouseover) | The server answers only for the current target; one tab = one target at a time. Switch cost = a new request |
**Impossible without server data:** threat of players not in your group; threat for a target you do not
have selected; threat on mobs while solo. A pure client-side estimate (damage + heal x modifiers) is
possible, but needs spell-by-spell threat rules (class talents, stances); not planned (see priorities).
Fallback if the server does not answer: offer a client estimate in v2 (damage done = 1 threat, healing
half, tank stance multipliers) labelled "estimate". Not v1.
---
## 4. Data model and release plan
### 4.1 Model
One feed, three levels. All tables are plain Lua tables, numbers only (no string keys per hit), so a
40-man raid for 15 minutes stays small.
```
meters = {
actors = { [guid or name] = Actor }, -- persistent across segments in a session
segments = { -- ordered, newest last
current = Segment,
overall = Segment,
history = { Segment, ... } -- last N fights, each has name, start, duration, boss flag
},
roster = { [guid] = actorKey }, -- group members, pets -> owner map
spells = { [id] = { name, icon, school } }, -- cache, filled lazily from GetSpellRecField
}
Segment = {
name, zone, start, stop, active_time, -- seconds
actors = { [actorKey] = SegActor }, -- only actors with data in this segment
deaths = { Death, ... }, -- ordered
enemies = { [mobKey] = { name, guid, damage_taken, damage_done } },
}
SegActor = { -- one actor in one segment
damage = Totals, healing = Totals, taken = Totals, healtaken = Totals,
power = { [powerType] = n },
active = n, -- activity seconds
interrupts = { count, [victimSpell] = n, [kickSpell] = n, targets = {[mobKey]=n} },
dispels = { count, [auraId] = n, [spellId] = n },
cc = { done = {...}, broken = {...} },
casts = { [spellId] = { start, go, failed, interrupted } },
auras = { [spellId] = { up = secs, applied = n, since = t } },
deaths = n, resses = n, cooldowns = { [spellId] = n },
avoid = { dodge, parry, block, miss, absorb }, -- as victim
}
Totals = { -- damage, healing, taken, ...
total, effective, overkill/overheal, absorbed, blocked, resisted,
hits, crits, misses, glancing, crushing,
spells = { [spellKey] = SpellStat }, -- spellKey = spell id, or name when no id (string feed)
targets = { [actorOrMobKey] = { total, spells = { [spellKey] = n } } },
pets = { [petKey] = n }, -- merged pet damage by pet
}
SpellStat = { total, hits, crits, misses, glancing, crushing, blocked, resisted, absorbed,
min, max, ticks, critTotal }
Death = { time, actor, killer, spell, overkill,
events = ring of { t, kind, src, spell, amount, hpAfter, crit } } -- 15 events, 10 s
```
Rules:
- Pets are keyed by their own GUID but belong to an owner (`roster`); views merge them into the owner and
list the pet as a sub-row. Merge toggle as in ShaguDPS (`merge_pets`).
- Keys use GUID when available (nampower), else name (strings). On a GUID's first appearance, resolve its
name with `UnitName(guid)` once and cache.
- `overall` is updated at event time alongside `current` (no merge at the end), as ShaguDPS does with the
two segments; closing a fight copies the compact `current` to `history` and starts a fresh one on the next
action by a group member.
- Views are *pure functions* of a segment: `view.Rows(segment, mode)` returns sorted rows (name, value, per-second,
percent, class, icon, tooltip builder); the UI never touches the raw tables. Drill-down is a view over a
single `SegActor` with a different row builder (spells / targets / breakdown).
- Memory guards: ring buffers for deaths, max 15 history segments, enemies capped at 80 per segment (trash
merges into "Other"), spell cache keyed by id.
- Combat time: segment active window from the first group action to the last action + 2 s (or
`PLAYER_REGEN_ENABLED` for everyone). DPS per actor uses their activity seconds (the second figure, as
in Details! "active time").
### 4.2 Feed layer
```
Feed.Damage(t, srcKey, dstKey, spell, amount, school, flags{crit,glance,crush,periodic}, absorbed, blocked, resisted)
Feed.Miss(t, srcKey, dstKey, spell, missType)
Feed.Heal(t, srcKey, dstKey, spell, amount, crit, periodic) -- overheal computed in the model
Feed.Energize / Feed.Cast(kind) / Feed.Aura(guid, spell, add|remove, srcKey?) / Feed.Dispel / Feed.Interrupt / Feed.Death / Feed.Res
```
Adapters: `nampower` (events), `chatlog` (GlobalStrings patterns; start from ShaguDPS's `sanitize` /
`cfind` approach and add the strings listed in section 2.2), `superwow` (UNIT_CASTEVENT, GUID tokens).
Adapter selection at login and on `/pfmeter probe` which prints what each source delivered, so the user
can tell whether nampower really supplies other players' events.
### 4.3 Priority list
**Release 1 (first meter release): "the numbers are right and the basics are complete"**
1. Feed layer, nampower adapter and string fallback, group combat/segment detection, pets merged, overall + current.
2. Windows: damage done, DPS, damage taken, healing, HPS, overhealing (with the HP-order probe done first),
absorbs victim-side, interrupts, dispels, deaths. One window, mode picker, segment picker, bar tooltips, reports.
3. Per-spell and per-target drill-down for every mode, with hit / crit / miss / glancing / min / max / avg.
4. Death log with last 10 s of events and heal markers (HP trail only where known).
5. Activity time and DPS on activity time.
6. Casts per player (counts by spell, incl. enemies' casts of the current target) - this is what the user
asked for by name ("all casts") and the data is already in the feed.
7. Threat window: request / reply / bars / pull line / own gauge / alert / "no data from server" message.
Replace TWThreat and OctoBG Threat's duplicates (OctoBG defers to pfUI).
8. Saved segments across reload (last ~10), reset prompt on instance entry.
**Release 2: depth**
9. Buff / debuff uptime (own, tanks, boss debuffs) and cooldowns used.
10. CC done and probable CC breaks; resurrections; friendly fire; avoidance; enemies view; power gained.
11. Multiple windows (snap, per-window mode and segment), threat tank view (`_TM` tail), threat history chart.
12. Segment naming by boss list, trash merge.
**Release 3: polish**
13. Absorbs attributed to shield casters, avoidable damage list, voidzones, consumable use.
14. Timeline charts; compare two players; user-curated spell tables (interrupt / CC / CD).
15. Optional sync between pfUI Octo users to cover players out of range.
**Not planned**: threat estimate when the server is silent (until proven needed), healing prevented, shield
remaining, other players' spell power snapshots.
### 4.3b Prior art on 1.12 (from a search-summary screenshot the user pasted, 19 Oct; not checked against the addons)
None of these are installed here. They show what vanilla players already use, so what the Octo meters must beat:
- **ShaguDPS** (github shagu/ShaguDPS, 3.0.1 installed here) - minimal damage / heal only, locale-independent
log parsing, no SuperWoW / nampower. Repo is **archived** (read-only since 1 Jun 2026), 122 commits, no
releases, and **no licence file** (the installed folder has none either), unlike pfUI itself (MIT).
So: use its *approach* (pattern sanitising, capture-index handling), write our own parser, and do not paste
its files into pfUI. The Octo meters have nothing to wait for from upstream.
- **Caw DPS Meter** - damage, healing, utility and aura uptime in one window; reads SuperWoW's raw combat log
and syncs data between players. Supports the plan: `RAW_COMBATLOG` (GUIDs in the log text) is a real
source on SuperWoW clients, and sync is what other meters do for out-of-range players. Probe 5 below
must confirm the event exists in this build (the only mention of it on this PC is a commented line in
`WhoDidIt\Chronicle\debug.lua`, so it is not yet proven here).
- **DPSMate** (github tdymel/DPSMate, 1.12.1, 852 commits, 97 stars, 70 open issues; the repo page shows no
last-commit date, so "newer than ShaguDPS" is not confirmed - it is simply the fuller one and not archived
as far as the page says). Its README module list is the best vanilla feature checklist and is a subset of
section 2.2: damage done / taken, healing, effective healing, overhealing, absorbs, healing taken, threat,
interrupts (incl. stuns and silences), deaths, buffs gained / lost / uptime, dispels (decurse, cure
disease / poison, lift magic as separate modules), CC breaker, compare mode, casts, procs, failed
actions, friendly fire, total / current / previous segments, report, multiple resizable frames, and
"synchronizing, to guarantee accurate data". Two new items for the spec: **procs** (aura gained from a
weapon / talent proc, from `BUFF_ADDED_*` with proc spell ids - available) and **failed actions**
(`SPELL_FAILED_*`, already counted under casts). It reads the combat log (install step: raise the
`CombatLogRange` settings in config.wtf, which confirms the string source is range-limited as in 2.3).
Licence **GPL-3.0**: incompatible with pfUI's MIT for copying code; read it for ideas only, copy nothing.
Lesson: keep per-hit tables out of the model (numbers only, ring buffers), as section 4.1 says.
- **GreedMeter** - combined damage + threat window; matches the plan of one window with a threat mode.
- **SW_Stats** - the old vanilla-era meter; log-string based.
- Raid logging services (LegacyLogs, Realmplayers) read the game's own log file, not a meter; out of scope.
### 4.4 Things to verify in game before coding (probe list)
1. Does `AUTO_ATTACK_OTHER` / `SPELL_DAMAGE_EVENT_OTHER` fire for **party/raid members and their pets**, and how far?
2. Heal event `amount`: gross or effective; ordering of `UNIT_HEALTH_GUID` vs `SPELL_HEAL_BY_*`.
3. Do the `*_OTHER` events run in parallel with the log strings (double counting)? Which CVars read back as 1?
4. Does the server answer `TWT_UDTSv4` at all on OctoWoW; what do `perc` and `melee` look like; does `_TM` give the tail?
5. Are `SPELLINTERRUPT*` / `DISPELLED*` / `UNITDIES*` GlobalStrings present with the same arg order as the TBC set; exact `RAW_COMBATLOG` support in this SuperWoW.
6. Range CVar ceiling for the combat log; what `IsInInstance()` returns here.
7. `SPELL_START/GO_*` argument tail (target GUID, flags, itemId) - one probe printing all `argN`.
Everything above rated **available** depends on probe 1 working; if it fails for other players, the string
adapter keeps items 1-7, 13, 16-19 working at the combat-log range and the model does not change.