SamandClaude Fable 5.1
23c14aaec1
The notes and comments say what is true of the 1.12.1 client and cite the byte address; the record numbers, the dates and the private repository's file paths go. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# `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).
|