186 lines
9.3 KiB
Markdown
186 lines
9.3 KiB
Markdown
# 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.
|