Skip to content

The shipper's events

For: contributors and anyone writing their own sender. At the end: you know every event and field the shipper sends.

What shipper/wow_stats.py sends and what wow-stats ui expects to read. Any receiver that stores these lines in VictoriaLogs (with feed as the stream field) works with the UI; the compose kit’s is POST /ingest on the UI itself.

the PC you play on server
shipper (launchd / Task Scheduler) --POST--> ui /ingest --> VictoriaLogs /insert/jsonline
1 archive WTF/ to a git repo (validates, all or nothing)
2 extract new events to a spool
3 ship the spool, then move it to sent/
  • POST <url> with basic auth (user wow by default), body newline-delimited JSON, Content-Type: application/x-ndjson. The shipper splits files into POSTs of at most 4 MB; the UI’s ingest refuses more than 8 MB (413).
  • 2xx means stored. Anything else: the shipper keeps the spool file and tries again on its next run, so a server outage loses nothing.
  • The UI’s ingest accepts a POST only when every line is a JSON object with a string _time and a feed starting with wow- (otherwise 400, nothing stored). It sets component to wow on every line (never the sender’s value), and forwards the lines to VictoriaLogs’ /insert/jsonline with _stream_fields=component,feed, _time_field=_time, _msg_field=_msg and Content-Type: application/stream+json (with any other type VictoriaLogs answers 200 and stores nothing).
  • VictoriaLogs drops events older than its retention on arrival: the compose kit sets 100 years, its default is 7 days.
  • _time: RFC 3339 UTC with milliseconds, 2026-11-17T15:14:03.120Z: the event’s own time, not when it was sent.
  • feed: wow-recorder, wow-level, wow-dungeon, wow-character, wow-gear, wow-bags, wow-quests, wow-player, wow-prices or wow-combatlog.
  • char: Name-Surname as in the WTF folder, Testchar-Demo. Polestar’s account data writes Testchar Demo (a space): the UI treats both as one character.
  • _msg: a short human line (Recorder events: the raw record line).
  • source_id: unique per event, so a resend or a --backfill is harmless: rec:<charId>:<chunkSeq>:<line>, level:<char>:<level>, dungeon:<char>:<entered>, character:<char>:<seen>, gear:<char>:<hash>, player:<source>:<player>:<epoch>, price:<realm>:<item key>:<day>, cl:<file>:<byteOffset>. The UI keeps the newest _time per source_id (then the highest rev).
  • Numbers are JSON numbers, booleans JSON booleans, names in snake_case.
  • demo: true only on dev/seed.py’s made-up events: the UI shows a DEMO DATA banner for those characters.

Never sent: the Battle.net account id or the account folder name.

wow-recorder (Polestar Recorder chunks): kind (pos, unit, combat, step, kill, rep, loot, offer, progress, zone, xp, skill, craft, accept, turnin, complete, abandon, death, level, taxi, land, ride, vendor, trainer, rest, afk, encounter, enter, session, text…), map_id, x, y when present, zone (the map name when the shipper can resolve it), and per kind what the record holds: quest_id, level, xp, xp_max, xp_gained (the change since the character’s previous xp record), money_copper, xp_reward, npc_id (with npc_name from LibForeverData’s NPC table on death, unit, kill, rare and loot records), item_names on loot records (a JSON object, item id to name, from LibForeverData’s item table; the loot history), step, guide. Unparsed values stay in args (a string). Records naming another player keep the name in player.

  • duration_s, computed by the shipper so the UI only adds up: on zone (until the next zone change or the end of the chunk), on step (since the previous step), on taxi (until land).
  • quest_name on accept, turnin, complete, abandon and fail: from LibForeverData’s quest table (Interface/AddOns/LibForeverData/Data/Quests.lua), else Polestar_QuestDB’s, else the quest title the Recorder saw in a text record. Missing when none knows the quest.
  • login: true on the first record after more than 2 minutes without any. The Recorder starts every 5-minute chunk with a session record, so those can’t tell a login from the next chunk; this flag can.

wow-level (Polestar.lua, PolestarCharDB.qol.xp.splits[level]): level, seconds (played time in that level), xp, quests, kills, partial; _time is the ding that ended the level. Polestar writes a split when a level ends, so the level being played has none yet. partial: true marks a split where tracking started partway through the level: the ding is real, the played time is short.

wow-dungeon (PolestarCharDB.instanceRuns): dungeon_id, name, level, seconds, xp; _time is when the run started.

wow-character (account PolestarDB.alts.chars): a snapshot saved at logout: level, xp, xp_max, money_copper, zone, race, class, faction, realm, bind, resting; _time is the snapshot’s time. Plus looks when Narcissus’s barber shop saved one (below).

Characters Polestar doesn’t track get one too, so every character of the account shows up: one event each time what is known about it changes (source_id carries a hash of the fields). They come from the character’s WTF folder (<realm>/<char>/, written at each login, even with every addon off) and Syndicator (SYNDICATOR_DATA.Characters[...].details and money): realm (the folder’s name), race, class, sex (male/female, Syndicator’s UnitSex), faction, guild, money_copper, and source, the files that know it (folder, syndicator, comma-separated). _time is the newest file in the character’s folder. A backfill of archived versions leaves these to the current tree: an old version’s file times are the extraction’s.

wow-character with kind: played (optional, Altoholic): /played as DataStore_Characters saved it. Fields: played_total_s and played_level_s (DataStore’s played and playedThisLevel, the game’s answer to the /played request it sends at every login and /reload), level (bits 0-6 of BaseInfo, updated at each ding), logged_out (lastLogoutTimestamp below 5000000000), source: altoholic; _time is lastUpdate, the save (the logout). The values are valid for an earlier moment, the last login or /reload before it, which DataStore doesn’t save: lastUpdate is rewritten at logout to the same time as lastLogoutTimestamp, so played + (lastLogoutTimestamp - lastUpdate) adds nothing. The UI never needs that moment (below: it anchors to a level start). source_id is played:<char>:<played_total_s>. The character comes from the entry’s name (“First Last”) else its key in DataStore_CharacterIDs.Set (Default.<realm>.<name>, any realm; never List, whose indexes shift when a character is deleted). Files: account SavedVariables/DataStore.lua and DataStore_Characters.lua; format read from Thaoky’s source (github.com/Thaoky/DataStore and DataStore_Characters, 2026-10-14 releases, the ones Altoholic_Forever depends on). Every other reader of wow-character leaves these out (-kind:=played): they carry no gold, zone or race.

wow-gear (the character sheet): one event each time it changes, for every character of the account (its folder, Polestar’s alts, Syndicator). _time is the character’s logout snapshot in PolestarDB.alts.chars (the moment the game wrote these files), else the newest of the files’ modification times. source_id carries a hash of the content, so a sheet that goes back to an earlier state is sent again with the newer time.

  • items: the equipped items, from the account’s Syndicator.lua (SYNDICATOR_DATA.Characters[...].equipped, a Lua array whose index is the inventory slot + 1): slot (1 head … 19 tabard), slot_name, item_id, name (from the item link), quality (0 poor, 1 common, 2 uncommon, 3 rare, 4 epic, 5 legendary), item_level and req_level from Polestar_ItemDB (Forever.lua over Items.lua; null when the item isn’t there).
  • item_level: the average over the equipped items, shirt and tabard left out.
  • professions: skill_id, name, rank, max_rank. Ranks from PolestarDB.alts.chars[...].profs (saved at logout), names and caps from the character’s CharacterExport-Forever.lua (professionCache); the higher rank wins when both have one.
  • wanted: the upgrades the player tracks in GearQuestForever (the character’s GearQuestForeverCharDB.hunts with status tracked): item_id, name, item_level, req_level, slot_name, level. ForeverLevelingBiS keeps no suggestions in its SavedVariables (it computes them in game), only the spec.
  • polestar_spec: Polestar’s Stat weights setting for the class (PolestarDB.settings.gear.spec[CLASS]): auto or a spec key such as shadow. gear_adjust: the player’s edits in Polestar’s Adjust weights window (PolestarDB.gearAdjust[CLASS]) as a list of {spec, stat, x} (a multiple) or {spec, stat, v} (a value): a list, because VictoriaLogs flattens nested objects. min_upgrade: Polestar’s smallest upgrade worth showing, in percent (settings.gear.minUpgrade). All three are account wide in Polestar and sent with each of its characters; gear advice (docs/gear-reference.md) reads them.
  • talents: points per talent tree, [{tree, points}] in tree order, from Vulcan SimBench’s last export (VulcanSimBenchCharDB.last in the character’s SavedVariables, written by /simx; Adler-32 checked). Only the points and tree names: the rest of that string (stats, gear) is never sent. Missing until the player runs /simx once.
  • spec (ForeverLevelingBiS, else GearQuestForever’s pick) and spec_from, the addon it came from (ForeverLevelingBiS or GearQuestForever), guild (from Syndicator, without the realm), class, race, faction, sex (male/female from Syndicator’s details.sex, for the 3D view; the full view only).
  • recipes: the recipes the character knows, per profession, from Altoholic’s DataStore_Crafts.lua (account SavedVariables), as a list of {profession, known: [recipe spell IDs], seen} (seen: how many recipes that profession’s window listed). Only professions whose window the character opened with Altoholic installed; missing otherwise. Gear advice says “learn the pattern first” or “find the recipe” from it, and never “make it now” without it.
  • class_train_level: the level of the last class trainer visit, from Polestar’s PolestarCharDB.classTrainVisit (the character’s SavedVariables), for the planner’s class trainer errand.

Never sent in wow-gear: the money Syndicator keeps next to the gear (it goes in wow-character, for characters Polestar doesn’t track), bag and bank contents (wow-bags, below).

wow-bags (what the character holds): one event each time the set of item IDs in its bags or its bank changes, from the account’s Syndicator.lua (SYNDICATOR_DATA.Characters[...].bags and .bank, Lua arrays of containers of slots; the bank as it was the last time the character opened it, empty when it never did). bags and bank are sorted lists of item IDs: no counts, no links, nothing else from the slots. A character whose bags Syndicator hasn’t scanned yet sends nothing; one that holds nothing sends empty lists, so an older list doesn’t stay the newest. _time is Syndicator.lua‘s modification time. The newest one is what the character has: the gear advice lists a held upgrade with its bag or bank as its only source (“equip it”), and so do the Overview, the plans and the MCP; the Dungeons panel marks a drop obtained (worn, in the bags or in the bank). No view shows the lists themselves. Both tiers’ allow lists stay as they were: /zogzog/ already has the advice’s sources[].kind and the panel’s where; the public site has no advice.

wow-quests (the quests the game says are completed): kind is completed, one event per character and source each time that source’s set changes. The Recorder only sees the quests handed in while it runs, so these carry the ones done before Polestar. quest_ids is the sorted list, n its length.

  • source: questie: Questie’s QuestieConfig.char[<"First Surname">].complete (account Questie.lua), the game’s full set as of the last login with Questie on. _time is the file’s modification time.
  • source: altoholic: DataStore_Quests’ DataStore_Quests_History[<id>].Quests (account DataStore_Quests.lua), the game’s set rebuilt 5 s after each login, 64 quests per number. The client saves each number with 16 significant digits and the addon builds it in a double, so in a slot whose high bits are set the low ones are lost: only the bits no rounding can have changed are sent (unknown counts the others, size is the game’s own count). Never sent when the addon’s AutoUpdateHistory option is off. _time is its LastUpdate.

wowstats.quests joins them with the Recorder’s hand-ins, the game’s “already done” flags in offer records, the gear only one quest gives (held: worn, bags or bank) and the quest chains (a quest done means the quests it needed were done), into the one “done” set the Dungeons panel, the plan, the gear advice and the MCP use. No page shows the lists.

Appearance. Battle.net’s profile API has it for every character it knows (the exporter, below); the shipper only adds a fallback for the others: looks on wow-character, a JSON list [{"optionId": 80, "choiceId": 1174}, ...], the newest look saved in Narcissus’s barber shop (Narcissus_Barbershop, account NarciBarberShopDB.PlayerData[<player id>].SavedLooks[<race id>][male|female], or SharedSavedLooks when the character uses the shared profile; druid and worgen alternate forms are left out). The player id is the end of the character’s GUID (Player-<realm id>-<player id>), read from the profession links that CharacterExport-Forever saves in the character’s own SavedVariables (|Htrade:Player-...). Syndicator and Polestar save no GUID of the character itself (Syndicator’s item links name the crafter, who can be anyone). Without CharacterExport-Forever, the name Narcissus saves (playerName) is used when only one of the account’s characters has it. The ids are the game’s, the same Wowhead’s viewer takes. A look that doesn’t fit the model (a race change) falls back to the default per option.

wow-player: one event per sighting of another player, from every source that names one (Polestar’s probe list, Recorder records, dungeon rosters, combat log party members): player (Name-Realm), context (seen, grouped, dungeon, quest-nearby, combat), zone/map_id when known, level, class/race when known, dungeon for dungeon runs. Player names are fields, never stream fields. Full view only.

wow-prices (the account’s Auctionator.lua, AUCTIONATOR_PRICE_DATABASE): one event per item and scan day, from the player’s own auction house scans.

  • Fields: item_id, item_key (Auctionator’s key: 2592, or g:4306:0 for some items), item_name (LibForeverData’s or Polestar_QuestDB’s item table), price_copper (the day’s lowest price), price_high_copper, available (items listed), scan_day (YYYY-MM-DD), realm, faction (only for houses Auctionator keys as “Realm Faction”). _time is the scan day’s local midnight.
  • Each realm’s table is a CBOR string (Auctionator 11+); the shipper decodes it with the standard library. Days count from 2020-01-01 local time.
  • Within a day the numbers only widen (the low only goes down, the high and the listed count only go up). The shipper merges the file, its .bak and what it sent before, and sends the day again with rev + 1 when it changed. The UI keeps the highest rev.
  • The shipper only reads the file (in WTF, or the archived versions during a --backfill), never writes it. Full view only.

wow-combatlog (Logs/WoWCombatLog*.txt, when combat logging is on): event (SPELL_DAMAGE…), _msg is the raw line, _time from the line’s own timestamp (the PC’s local time, converted to UTC).

wow-setup (the shipper’s own check, no character): addons (the addons of docs/videos/steps.json found in Interface/AddOns, id to its .toc version), recorder_on (Polestar Recorder’s switch, PolestarRecorderDB.enabled; missing when no account saved it yet), saved_chars (how many characters have Polestar’s saved data), shipper (the shipper’s own version; missing from one older than its auto-update, which /start then asks to update once by hand). Sent with each send, when it changes, and once a day; no folder, name or character. The start page (/api/me/status setup) and the “Missing:” lines (wowstats/missing.py) read the newest one; it is not game data, so it counts for nothing else.

  • Header, climb, zones, guide steps, dungeons, deaths, flights: wow-recorder, wow-level, wow-dungeon, wow-character. The climb’s totals (played time, kills, quests) are sums over the wow-level splits; the Recorder’s records only cover the time it was on.
  • Played time, everywhere (the climb’s x axis, pace, ETA): logged-in time, never calendar time. Finished levels use their split. The level being played has no split yet, so its time so far comes from the Recorder: it opens a chunk (a session record) every 300 s while the game runs, so a silence over 315 s is time offline, and the rest adds up to the same logged-in time Polestar’s splits count (level 31 of the test character: 9369 s both ways).
  • Total played since level 1: only with Altoholic (kind: played above). Its /played is the game’s answer at a login, so played_total_s - played_level_s is the moment that level began; the UI adds that level’s split and every later one, plus the level in play, so the total is current. A snapshot whose session had a ding is skipped (the answer may be from the level before), and so is one from a level before tracking began. Without one, the climb says “played since tracking began”. Polestar’s own addons don’t save /played.
  • Guide steps: a step record with reason: pick is the player picking or switching guide (its step is often empty): listed as “Picked guide …”, never counted or timed as a step. Numbered steps show the step’s own text from the route reference when the guide is in it.
  • Gear and professions panel: the newest wow-gear event. The public view shows it too (no gold in it).
  • Journal: one entry per play session. A session ends after 20 minutes without any Recorder record, or at a login record. Each entry has start, end, played time, levels gained, XP, zones (time clipped to the session), quests handed in with names, deaths per zone and dungeons. The full view adds the players met and the gold change (the logout snapshot after the session against the last one before it).
  • Prices panel: wow-prices, full view only.