39 KiB
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 " 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 | 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_OTHERcounts with the log lines for a player standing 80 yd away. - SuperWoW
UNIT_CASTEVENTfollows 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:
- Request. The client sends an addon message with prefix
TWT_UDTSv4and textlimit=NoverRAID(when in a raid) orPARTY(in a party).N= how many players the server should list (TWThreat sends visible bars minus one, OctoBG sends 10). A variant with prefixTWT_UDTSv4_TMadditionally 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. - 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.
- Reply. A
CHAT_MSG_ADDONevent; the payload text (arg2, notarg1, which is the prefix field) contains the markerTWTv4=followed by entries separated by;, each entryname: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-1for the player who currently holds aggro, else0,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-1if the player is in melee range of the mob (decides 110 % vs 130 % to pull).
- Tank-mode tail. If the message contains
#followed byTMTv1=, the part after#is a second record listcreature:guid:name:percjoined 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_TMmode. OctoBG currently drops it. - 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 -> threathistory from each reply; TWThreat uses 1 s buckets fromtime()). - 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_CHANGEDevent. Needed only for tank mode.
- 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. overallis updated at event time alongsidecurrent(no merge at the end), as ShaguDPS does with the two segments; closing a fight copies the compactcurrenttohistoryand 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 singleSegActorwith 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_ENABLEDfor 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"
- Feed layer, nampower adapter and string fallback, group combat/segment detection, pets merged, overall + current.
- 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.
- Per-spell and per-target drill-down for every mode, with hit / crit / miss / glancing / min / max / avg.
- Death log with last 10 s of events and heal markers (HP trail only where known).
- Activity time and DPS on activity time.
- 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.
- 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).
- 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 inWhoDidIt\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 theCombatLogRangesettings 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)
- Does
AUTO_ATTACK_OTHER/SPELL_DAMAGE_EVENT_OTHERfire for party/raid members and their pets, and how far? - Heal event
amount: gross or effective; ordering ofUNIT_HEALTH_GUIDvsSPELL_HEAL_BY_*. - Do the
*_OTHERevents run in parallel with the log strings (double counting)? Which CVars read back as 1? - Does the server answer
TWT_UDTSv4at all on OctoWoW; what dopercandmeleelook like; does_TMgive the tail? - Are
SPELLINTERRUPT*/DISPELLED*/UNITDIES*GlobalStrings present with the same arg order as the TBC set; exactRAW_COMBATLOGsupport in this SuperWoW. - Range CVar ceiling for the combat log; what
IsInInstance()returns here. SPELL_START/GO_*argument tail (target GUID, flags, itemId) - one probe printing allargN.
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.