Files
2026-11-16 01:00:42 +01:00

9.3 KiB
Raw Permalink Blame History

ChronicleCompanion — extra log events

Extra log lines for deeper raid analysis, written by advancedlogging/ursol.lua on top of everything ChronicleCompanion already logs.

The file is named after "Ursol", the TurtleWoW 1.18.1 client patch, now used by the servers that came from TurtleWoW (OctoWoW, Capybara, Ravencraft, ...). Nothing in it is tied to one server: every line type runs only when the client provides what it needs, so a plain 1.12 client with Nampower logs what it can and the rest stays off, without errors.

All lines keep the usual layout TIMESTAMP_MS|EVENT|field|.... The event names are new, so Chronicle skips them (checked with Chronicle's own parser on a real Onyxia log with tens of thousands of extra lines, including UNIT_STATE: 0 errors, identical results). Existing events are unchanged, except HEADER and ZONE_INFO, which get new fields appended at the end (see below).

Requirements

Feature Needs Without it
UNIT_STATE (health, power), UNIT_TARGET, UNIT_COMBAT Nampower with GetUnitField off, events not registered
UNIT_STATE position fields ClassicAPI (any visible unit) or SuperWoW (friendly units only) fields left empty, no position poll
RAID_MARK GetRaidTargetIndex and unit GUIDs (Nampower GetUnitGUID or SuperWoW); markN tokens of ClassicAPI / SuperWoW make it more complete off
THREAT, THREAT_TANK the Ursol client and a server with the TWThreat threat API; TWThreat or pfUI-ThreatPlates optional nothing written; requests stop by themselves (see threatQuery)

These requirements are detected independently. A native build 5875 client with Nampower can log health and power, and gains positions when ClassicAPI or SuperWoW supplies UnitPosition; it does not need the Ursol client for those features.

Line types the client cannot produce are greyed out in the options panel with the reason, and marked (off: ...) in /chronicle ursol. The saved setting is kept, so it comes back when the required provider is available.

Events

HEADER and ZONE_INFO (existing lines, extra fields)

0|HEADER|playerGuid|realm|zone|addonVer|superWowVer|namPowerVer|xp3Ver|wowVer|wowBuild|wowBuildDate|localTime|utcTime|combatLogRange|classicApi|threatMode

  • superWowVer: the existing slot is filled again with SUPERWOW_VERSION (empty without SuperWoW).
  • classicApi (new, at the end): ClassicAPI version X.Y.Z, decoded from CLASSIC_API_VERSION (major × 10000 + minor × 100 + patch); empty when ClassicAPI is not loaded, unknown for a build without that global.
  • threatMode (new, at the end): query (this addon asks the server), listen (TWThreat / pfUI-ThreatPlates ask, this addon records the answers) or empty when threat logging is off.

ts|ZONE_INFO|zoneName||inInstance|instanceType|isGhost|mapId

  • The slot after the zone name stays empty: Chronicle uses it as an internal instance number.
  • mapId (new, at the end): the Map.dbc id (ClassicAPI GetInstanceInfo), e.g. 309 for Zul'Gurub; empty without ClassicAPI.

UNIT_STATE

ts|UNIT_STATE|guid|hp|maxHp|power|maxPower|powerType|mapId|x|y|z

Health, power and position of one unit on one line, written only when one of them changes (position: a move of more than positionMinMove yards).

Field Content
hp, maxHp current and max health
power, maxPower current and max value of the unit's current power type
powerType 0 mana, 1 rage, 2 focus, 3 energy, 4 happiness
mapId Map.dbc id (ClassicAPI), e.g. 309 for Zul'Gurub; empty without ClassicAPI (same value as in ZONE_INFO)
x, y, z world coordinates in yards (1 decimal), x = north, y = west whatever the API

Empty fields mean "not available" (no power, out of position range, etc.). Rage is converted to the usual 0–100 scale (the unit field stores ×10).

Units: group members, their pets, and hostile creatures seen in combat events during the last 15 s. Lines come from:

  • Nampower UNIT_HEALTH_GUID / UNIT_MANA_GUID / UNIT_RAGE_GUID / UNIT_ENERGY_GUID, written right away (same timestamp as the event);
  • a poll of tracked hostiles every targetInterval (0.25 s);
  • a position poll every positionInterval (1 s), only while you are in combat.

Notes:

  • Health and power come from Nampower. ClassicAPI and SuperWoW are not needed unless positions are enabled.
  • SuperWoW positions are limited to friendly units. Hostile coordinates can be empty even when their health and power are available.
  • ClassicAPI supplies the per-unit mapId. Without it, SuperWoW coordinates can still be logged, but mapId is empty unless the current map was identified separately through ClassicAPI GetInstanceInfo.
  • A druid's power is the one of their current form: energy in cat form, rage in bear form, mana otherwise. The caster mana is not visible while shifted.
  • Check maxHp for creatures. If it is 100, the server sends a percentage instead of real hit points.

UNIT_TARGET

ts|UNIT_TARGET|guid|targetGuid

Target of each tracked hostile creature (empty = no target), polled every targetInterval (0.25 s), written on change. Gives who is tanking and when a boss switches target.

UNIT_COMBAT

ts|UNIT_COMBAT|guid|inCombat

A hostile creature enters (1) or leaves (0) combat. Read from the "in combat" bit of the unit flags (UNIT_FLAG_IN_COMBAT, 0x80000), on Nampower UNIT_FLAGS_GUID and during the poll of tracked hostiles (targetInterval).

  • 1: the mob was pulled (or joined the fight). Mobs only seen idle write nothing.
  • 0 after a DEATH of the same unit: it died.
  • 0 with no DEATH: it reset / evaded (wipe, kited too far, leash). Its health goes back to max and it walks back to its spawn, visible in UNIT_STATE; attacks on it during the walk back come out as "Evade" in SWING / MISS.
  • A mob that goes out of range while in combat is forgotten after 60 s without a 0 line: how its fight ended is unknown.

ts|RAID_MARK|guid|index

Raid icon 1–8 set on a unit, 0 when removed. Scanned 0.3 s after the last RAID_TARGET_UPDATE of a burst, on enable, and every 5 s in combat. A removal is written when the icon moves to another unit, or when the unit is missing from two scans in a row (a single scan can miss a mark for a moment).

THREAT

ts|THREAT|mobGuid|mobName|source|list

Server threat table of one mob: player:tank:threat:perc:melee;... (tank/melee = 1 or 0, perc = % of the tank's threat, rounded to 1 decimal: the server sends 100.000000). source:

  • self: answer to a TWT_UDTSv4_TM request from this client (this addon, TWThreat or pfUI-ThreatPlates). mobGuid is your target when the answer arrived.
  • relay:<Name>: a TWTRelayV2 message shared by a group member (TWThreat or pfUI-ThreatPlates). mobGuid is that player's target, empty if it could not be confirmed.

The same table received twice within 1.5 s is written once.

THREAT_TANK

ts|THREAT_TANK|source|list

"Mobs I am tanking" list: creature:serverGuid:nextPlayer:perc;... (perc rounded to 1 decimal). source is self (TMTv1 answer) or relay:<Tank> (PFTPTankV1 share). serverGuid is the server's decimal form, not the 0x… form.

Settings

The options panel (/clog or /chronicle config) has an Extra events side panel on its right: one checkbox per line type (the Positions line shows which API gives them) and an Ask the server checkbox under Threat (checked = threatQuery on, unchecked = auto; off is set with the slash command). The ClassicAPI and SuperWoW versions are listed under Version Info in the main panel, next to Nampower. Intervals are only in the slash command: /chronicle ursol lists the settings, /chronicle ursol <setting> <value> changes one.

Setting Default Meaning
unitState, target, combat, marks, threat on turn each line type on/off
position on add positions to UNIT_STATE and poll them in combat
targetInterval 0.25 seconds between target / combat flag / hostile health and power polls
positionInterval 1 seconds between position polls (in combat)
positionMinMove 0.5 yards a unit must move before a position change alone writes a line
threatQuery on auto: ask the server only if TWThreat and pfUI-ThreatPlates are absent, and stop after 10 requests without any answer (server without the threat API; an answer, even relayed by the group, turns them back on); on: always ask; off: only listen
threatInterval 1 seconds between threat requests
threatLimit 40 players per threat table requested (40: the whole raid, low-threat players included)

Threat requests stop after 10 without any answer in on mode as well as in auto (a server without the threat API is not asked every second); an answer, even relayed by the group, turns them back on.

Limits

  • Only units your client sees are logged. Several raiders logging together cover the whole raid.
  • Group members and pets are logged directly. A target, mouseover, or nameplate unit is not logged merely because it has that token; hostile units must also have been seen in a combat event and remain in the 15-second tracking window.
  • The server only answers threat for your target. Shared relays from the group fill in the other mobs.
  • File size grows with UNIT_STATE lines. Not measured yet in a 40-man raid: check the first log and raise the intervals if needed.