Files
WhoDidIt/CLAUDE.md
T
bdot1andClaude Opus 5.5 b5d31d0c69 v1.27.0: an own numbered Chronicle log file for every raid and 5-man
Players couldn't find their logs. Chronicle writes everything (raids,
5-mans, the open world) into one Chronicle_<Name>.txt, and its "logs from
a previous instance ID" pop-up fires after a relog mid-raid (the lockout
isn't loaded yet) - its Archive moved the night's MC log (40 MB) into
Chronicle_Upsilon_backup_1792093482.txt and the dungeon after it started
a new main file (15 Oct 2026).

Now (opts.chronSplit, on by default, built-in logger only) every raid run
and every 5-man run gets its own file, Chronicle_<Name>[_<Realm>]_<NNN>_
<Zone>.txt; the open world and battlegrounds keep Chronicle's own file.
- Entering a raid pops up its log number and file (and asks, if logging
  is off); "Don't log this raid" skips one raid, Chronicle's auto start
  and the boss-pull start included. No Escape on it (1.12 maps Escape to
  the second button).
- A relog, a run back or a 5-man in between keeps the raid in its file;
  a new lockout (both IDs known and different) or 6 hours without a line
  starts a new one; an unknown lockout (0) never does. 5-mans: same zone
  within 2 hours.
- The file is picked once the zone text settles (a known raid name, 5 s,
  or the first pull); a 5-man file picked on a lagging name is renamed
  while nothing has been written to it.
- Chronicle's stale-instance pop-up is skipped (each lockout has its own
  file). Chronicle's files aren't edited: GetLogFilename, FlushToFile and
  WriteZoneInfo are wrapped from Logs.lua.
- The Chronicle Logs tab shows the log number, the last 10 files with
  their lines, a switch back to one file, and matching upload steps.
  New texts in all nine languages; zh font subset rebuilt.

Checked offline: Logs.lua with a fake Chronicle that copies the real
one's file, zone and stale-instance behaviour, through an evening of MC,
a relog, a 5-man, back to MC, lagging zone names, Don't log, a new week,
never asked, split off and a battleground: 28 checks pass. LuaCheck on
every changed file. Not tried in game; chronicleclassic.com accepting the
new file names is unconfirmed (the content is unchanged).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 21:20:22 +01:00

13 KiB

WhoDidIt - notes for Claude Code

Starter from Shemp's review (6 Oct 2026), extended with what this project taught us.

Platform

World of Warcraft client 1.12.1 (TurtleWoW / OctoWoW), Lua 5.0, with SuperWoW and Nampower.

  • No #t (use table.getn), no % operator (use math.mod).
  • No string.match or string.gmatch (use string.find and string.gfind).
  • Strings have no methods: s:find() fails, write string.find(s, ...).
  • Varargs only through the arg table. Handlers read the globals this, event, arg1..arg9.
  • Widget API is 1.12: no SetSize, SetShown, SetColorTexture, HookScript, C_Timer, hooksecurefunc.
  • SavedVariables of an addon are loaded after its files and before its ADDON_LOADED.
  • UnitBuff(unit, i) returns texture, count, spellId. UnitDebuff has the dispel type before the id.
  • A function may reference at most 32 upvalues; a file may have at most 200 top-level locals (UI.lua is close: put new things on the UI table instead of new top-level locals).
  • gsub callbacks must return a value (nil deletes the match in 5.0).
  • The client reads the .toc and Bindings.xml only at start-up: new files need a full restart (or ClassicAPI, which makes /reload pick them up).
  • ClassicAPI is optional: everything must work without it (check W.env.classicapi).
  • Chat: "|" starts a colour / link code, lines max out at 255 bytes, say / yell / channels have a spam limit (WhoDidIt sends one line a second there).
  • Custom chat channels are split by faction: a master only feeds its own faction.
  • math.randomseed is called once at load (Core.lua).
  • Windows Script Host reads a .vbs written as UTF-16 with a BOM, so paths with umlauts survive; written as ASCII they turn into "?" (tested with cscript).
  • Both Karazhan towers report GetRealZoneText() "Tower of Karazhan" (WhoDidIt's fights, RollFor, BigWigs, AutoMarker). Chronicle calls them "Lower Tower of Karazhan" (Lower Karazhan Halls, 10 players) and "Upper Tower of Karazhan" (40). Data.lua D.sharedZones / Board.lua B.RunZone tell them apart by GetRaidRosterInfo's 7th return (zone); that value isn't checked in game yet.
  • GetRealZoneText() can lag behind a loading screen: inside LBRS it said "Blackrock Mountain" (subzone "Blackrock Spire") for a while after a ghost run-back (Shemp, 14 Oct 2026), and v1.26.0 lost the run's first 67 minutes. Never decide on one reading after PLAYER_ENTERING_WORLD: Dungeons.lua arms a run without the zone and re-reads it every second (settle: a run started on a lagging name is renamed, a replaced unfinished run waits in r.prev).

Before every commit

  • Every .lua file must load under a real Lua 5.0 interpreter (syntax check). There is no interpreter on the maintainer's PC yet; until there is, at least balance-check blocks.
  • Never guess an API. Find a call in an addon that is known to work on this client, or print the return values in game first and write the result into this file.
  • Re-read the diff as a reviewer and try to break it. Say what you checked and what you did not.
  • Edits must not halve backslashes: Lua paths are written "Interface\Icons\..." in the source. Shell heredocs and perl replacements have dropped them before; check after editing.
  • The working tree uses CRLF line endings; normalise before exact-text replacements.

House rules

  • Anything that posts to a shared chat channel, changes loot or raid marks, disables another addon or deletes data is OFF by default and asks before the first use.
  • A plain click shows things in the player's own chat; posting needs Ctrl-click or a button.
  • Never touch another addon's SavedVariables or its enabled state without asking the user (W:AskHandover).
  • Data received from other players or from the web is untrusted: check length and characters, and never repeat it in a public channel automatically. Other guilds' names only go out after the player has seen the exact text (W:ConfirmSend).
  • The master feed is only accepted from the characters in B.MASTERS (Board.lua). A player can only remove (and re-add) those; nobody else can be added.
  • In a raid only the leader and assistants post or steer the raid (W.CanLead in Core.lua). W:Send sends anyone else's posts to their own chat (W.LeadOnly says why, once), claims for automatic posts only count leaders, and the loaders wrap DopingControl's report / whispers and RollFor's raid chat (master looter allowed) without touching their files.
  • A message kind that is accepted without the trusted-sender check must not make anyone else send, store or compute without a cooldown and a cap (A and Q in Board.lua are rationed).
  • Raid times only come from the master feed and the download: players never send K / C records, B:Receive ignores them, and B:PurgeShared removed the ones received before 1.23.1. Your own recorded times stay on your PC.
  • Every table keyed by a GUID, a name or an error text needs an eviction rule.
  • Every Lua function may use at most 32 upvalues: check the big ones (FeedReceive, the feed ticker in Board.lua) when adding file-level locals they use.
  • Code from other repositories enters this one through a reviewed commit, never through a bot. Embedded addons are pinned to tested commits (tools/EmbedUpdate.ps1, Pin).
  • DopingControl moved to octowow.st/git/ShempError/DopingControl with 0.7.0 (a fresh one-commit repo; GitHub stops at 0.6.4). That host shows git, PowerShell and the updater an anti-bot page, so its spec is Manual: download /archive/.zip in a browser and run EmbedUpdate.ps1 -Only Doping -FromZip (the zip's comment is the commit; another commit is refused). Don't make the tool pass as curl to get round the challenge.
  • 0.7.0 replaces the global SendAddonMessage (scan/pull.lua, pass-through, pcall-guarded: every WhoDidIt send goes through it) and its Addons tab sends BigWigs / TWT / Rinse queries to the raid and SWOW_Q to GUILD (tab open, at most every 30 s, never in combat). Reviewed 15 Oct 2026: no loader wrap needed.
  • Event handlers run through pcall. Errors are printed once and kept for bug reports (/wdi errors).
  • Blame needs evidence. When the data is ambiguous, show it as information with 0 points.
  • One feature per commit.
  • Raid scaling eras: D.SCALING.at in Data.lua and $ScalingCutoff in tools/WhoDidIt-Sync.ps1 must stay equal (6 Oct 2026 04:54 UTC). Boards "kills+" / "clears+" hold the bests since then; the helper writes them as C2 / K2 lines and the feed sends them as "c!," / "k!," records (older clients skip those). Chronicle's leaderboard can't filter by date, so clears since are worked out from the raid logs (bosses every top run killed, time of the last one).
  • PackData.lua (WDI_MARKDATA) ships the Auto Marker's raid pack data, converted from AutoMarker's NPCList.lua (Weird Vibes) at the pin in tools/MarkDataUpdate.ps1, data only, credited in the file and README, not under WhoDidIt's MIT licence, removed if the author asks. Rebuild it only with that script from the real upstream file, never from edited copies.
  • Players install WhoDidIt by drag and drop only: nothing may tell them to run a CMD/PowerShell file (ClassicAPI, a DLL, is the one optional exception). Chronicle, RollFor\ and DopingControl
    ship in the repo at the pins in tools/EmbedUpdate.ps1 (maintainer tool: move a pin, run it, review, commit), each with WDI_NOTICE.txt. The sync helper and AutoSync are maintainer-only (they refuse to run on a PC without a B.MASTERS character).
  • Chronicle log files (Logs.lua, opts.chronSplit, built-in logger only): every raid / 5-man run gets its own numbered file through a wrapped ChronicleLog.GetLogFilename (L.target), picked once the zone settles; FlushToFile is wrapped to count lines per file, WriteZoneInfo to clear lastInstanceIds (Chronicle's stale-instance pop-up fired after a relog, when GetSavedInstanceInfo isn't loaded yet, and its Archive hid the raid in a backup
  • A dead boss must not start a fight (Tracker.lua slain / deadBoss): Golemagg's Magma Splash kept ticking after his death and each tick became a 0:03 "kill" that also saved the Chronicle log (MC, 15 Oct 2026).
  • The built-in Chronicle logger logs nothing until the player says yes (opts.chronUse). It stands down only while a separate ChronicleCompanion is actually loaded. A disabled or deleted one doesn't count: WTF keeps "ChronicleCompanion: disabled" after the hand-over or after the folder is deleted.
  • 5-man rankings (Dungeons.lua, W.Runs): D.DUNGEONS in Data.lua (level-60 dungeons, final bosses, splits, art). A run = first pull after zoning in -> final boss death. Members agree on WDI5 (party/raid addon channel): any opt-out (opts.no5man) keeps it private; time = the longest anyone timed; the leader (else first name) names and shares it. Channel record "D" (Board.lua hands it to W.Runs:Receive) is only accepted from a member; group names are untrusted (R.OkName). Masters write CustomData\WhoDidIt_Runs.txt (R5 lines + |ok) for Publish-RaidTimes and tools\Website-Export.ps1 (JSON for the website; upload off until tools\website.json, which is gitignored).
  • A member withdraws a wrong 5-man run (R:Withdraw, asks first): a run = dungeon + group key + seconds. The withdrawal (WhoDidItDB.runsWithdrawn) makes R:Merge refuse that run for good, so it can't come back from members' PCs, older versions or the download. Record "W" (keysecsnames) only from a member, 5 per sender per 10 min, 200 kept per realm (yours always, ones that took a run off before ones that never did); taking one makes nobody send, members re-send theirs in R:Answer. Masters write W5 lines; Publish-RaidTimes publishes them under the R5 ok rule and R:Seed applies them. Older clients ignore W (B:Receive drops unknown kinds) and keep sharing the run until they update.
  • Character names in the repository (RaidTimes.lua) or an export: the maintainer chose option (b) of review 3's T1 (9 Oct 2026). rec.ok (Dungeons.lua addOk) holds the members this PC saw share a run themselves: their own WDI5 vote, or the run sent by them on the realm channel (the server says who sent it; never what a message claims). Only those are named; Publish-RaidTimes takes a run only when every member is in ok, Website-Export shows the rest by class. Any other place that would publish names needs the maintainer's decision and a README line.
  • The guild's Hall of Fame (GuildFame.lua, W.GuildFame): each saved fight of the guild (rec.guild = Board's RaidGuild) becomes a card "recorder:n", swapped on SendAddonMessage "WDIG" GUILD (V = have per recorder, C = card chunks, X = card that doesn't count, F = skip). Twin fights (same enc, 5 min, 20 s): the smallest id counts, so every PC agrees. Sending your own needs opts.gfame (asked once). 800 cards / 4000 ids / 300 recorders / 3 guilds kept.
  • RaidTimes.lua (WDI_RAIDTIMES) ships every guild's raid times from the maintainer's sync (tools/Publish-RaidTimes.ps1: C/K/C2/K2/L lines, R5 only when every member is in ok, no PC/PK; refuses in a line, since it's a Lua 5.0 long string). B:SeedSnapshot puts it into the saved feed when it's newer, so the feed only sends what's newer; FULL_AGE is 21 days so a few-weeks-old snapshot asks for an update.
  • The maintainer's sync helper commits and pushes RaidTimes.lua by itself once a week (Publish-RaidTimes.ps1 -Auto; it skips when main has unpushed commits). Pull --rebase before pushing; never stage RaidTimes.lua with other changes.

Languages (Locale.lua, Locales*.lua)

  • English is written in the code and is what WhoDidIt saves and sends: fights, boards, the feed, addon messages. Text is translated only when it's shown, never before it's stored or sent.
  • New text a player sees: W.L("text"), W.LF("format %s", v) (string.format after translating), W.LT(sentence) for a sentence a fight saved in English (matched against S(...) patterns). Button SetText (UI.Skin), header labels (UI.SinkText), W.Print, W:Prompt, W.ShowPopup and the tooltip helpers already translate; W.L of a translated or unknown text returns it unchanged.
  • Then add a T("English", de, fr, es, it, pt, ru, zh, ko) line to the matching Locales file (9 strings, "" = English). Placeholders the same and in the same order, or numbered (%1$s, %2$d). Keys must be the exact English, escapes included ("\n", "\"), colour codes too (or translate the inner text: W.L unwraps one "|cffxxxxxx...|r").
  • Locale.lua loads after Core.lua, which has English stand-ins (W.L etc.), so a /reload after an update that adds files still works (in English, without flags) until WoW restarts.
  • The language is known at ADDON_LOADED: UI.Relabel translates the window built in English, then UI.FitAll shrinks labels that don't fit. Changing language = ReloadUI (Loc.Set, not in combat).
  • Chinese / Korean use Fonts\WDI-NotoSansSC.ttf / KR.ttf, subsets with only the characters the zh / ko columns use: run tools\FontSubset.ps1 after changing those translations (it stops when a character is missing). WoW's own tooltip and pop-ups use the client font: WhoDidIt uses W.TT and W.ShowPopup.
  • Chat: a translated line can be longer (Chinese / Korean letters are 3 bytes in UTF-8); split at 255 bytes on a character boundary.