benilla-octo/reference/README.md

reference/: verified facts about the 1.12.1 client, vendored

Generated tables describing the reference client, committed so benilla can measure itself against them on any machine without re-deriving them. Data, not documentation: each has a generator beside it in scripts/.

Nothing here is Blizzard content. A catalogue of names is not the thing named, the same way a comment may quote a byte address and docs/MAP.md may name a file.

1.12-globals.tsv

The 1.12.1 client's entire global namespace: 21,555 names, name<TAB>type<TAB>origin.

Where it comes from: a dump of _G inside the running reference client, which is the surface an addon sees (FrameXML-defined globals as well as engine ones), unioned with every global the shipped UI defines. The union matters because the twelve Blizzard_* addons are LoadOnDemand: a live dump only carries their globals if their windows were opened first, so the 1,986 rows a dump cannot see carry type lod. The table answers "is this a 1.12 name?", not "was this name live in one session".

The origin column says whose job it is to provide the name, attributed by its definition site in the complete 1.12 shipped-UI corpus:

origin	count	meaning
engine	1,104	the C client provides it; benilla implements these in Rust
framexml	20,427	the shipped UI defines it; the stock files run off the player's own install (ui_script::reference_ui)
lua	24	Lua 5.0's own runtime

The framexml bulk is UI objects, ContainerFrame1Item16IconTexture and its 11,000 siblings, which materialize from the XML and are nobody's to implement. The number that matters for the API surface is the function split: 1,100 engine functions, 1,075 FrameXML functions. A name defined in shipped Lua is FrameXML's, and hardcoding it in Rust is a category error even when it works.

Regenerating: scripts/gen-reference-globals.py, whose header carries the method and the traps. It needs a 1.12 install and the maintainer's runtime capture of the reference client's _G (WOW_RE=<that analysis>), which is not in this repo, so it is a manual regeneration. The table is stable: it describes a client that shipped in 2006.

Reading it: scripts/api-coverage.sh asks a real UiScript::new() what benilla exposes and reports have / missing / beyond-1.12. crates/benilla-ui/src/script/tests/reference_surface.rs is the gate: it fails if benilla grows a global that 1.12 does not have and nobody wrote down why.

1.12-shapes.tsv and 1.12-events.tsv

The binding-shape table (what each Lua verb takes and returns, gated by ui_script/shape_gate.rs) and the event table with the arguments each producer pushes (gated by ui_script/event_shape_gate.rs). Each file's header carries its column contract.

Regenerating: 1.12-shapes.tsv is vendored as the reference analysis writes it. scripts/gen-reference-events.py derives 1.12-events.tsv from two more vendored tables, 1.12-event-catalog.tsv (event id to name, off the client's name-pointer array) and 1.12-event-firesites.tsv (every fire site with the format string it pushes), so it runs from any clone and reproduces the committed file byte for byte.

1.12-message-catalog.tsv

The client's message registry (0xb4b498: id, key, kind, sound, chat type). scripts/gen-message-catalog.py re-shapes it into crates/benilla-ui/src/messages/catalog.rs, the table CGGameUI::DisplayError indexes.

1.12-verb-events.tsv

Every event the reference fires from inside a Lua verb, keyed by the verb: the verb's own body, or a helper that only registered verbs call (0x4d8c90 is the trainer's). The two tables above say what an event carries and whether something fires it; this one says who. A stock file that calls a verb for its side effect of an event repaints nothing when the verb fires nothing.

Regenerating: scripts/gen-reference-verb-events.py, whose header carries the rule, the two families it drops (glue-space verbs, the unit-field bridge) and why getters are excluded (a getter's fire is a cache-miss re-query, a state event benilla's feeds fire off the packet). A fire site is attributed to a function by the verified function extents plus the disassembly's padding boundaries, and a site past its candidate's extent is left out rather than mis-filed. The fire sites and the shapes are the vendored tables above; the function names and the disassembly are the maintainer's (WOW_RE=<that analysis>), so this one is a manual regeneration.

Reading it: crates/benilla-app/src/ui_script/verb_event_gate.rs is the gate. For every pair whose verb benilla registers, the module that registers the verb fires the event, or the pair is declared there: ELSEWHERE (a feed fires it on the state the verb changes, and the named file is checked too) or GAP (nothing does, with the reason).