Files
pfUI-Octo/docs/meters-spec.md
T
2026-10-19 10:36:44 +01:00

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_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.