chairmanpow
26d714fd1d
Fork policy (docs/METHOD.md): upstream structure wins; local-unique work re-applied on top. This commit is the upstream half of the reconciliation. Upstream is the same program at a rewritten history (884dff77==4e0e89cbtree), so the merge base was replaced to keep a real three-way diff. The large conflicts are upstream moving first: the UI manifest (benilla.toc -> the binary LAYER_MANIFEST/layer.toc split), the CVar table (cvars.rs -> cvars/{mod,table}.rs, +24 video rows), the editbox flush model, the host-side GetTime, the Options* -> BenillaOptions* rename, expanded ui_unit.rs, and a rebuilt volumetric_light.rs. Local-unique pieces re-instated on the upstream structure: - OptionsFrame.xml: the 1.12 OptionsFrameSliders table restored under the Benilla rename, with the TurtleWoW deviation note (patch-4 replaces OptionsFrame.lua). - layer.toc: CharacterFrameAdapters.xml (the sixth TurtleWoW character tab). - ui script: wipe/sizeof, BenillaGetMerchantItemStats, and the attach/mount teardown re-walk all survive. - game_plugins.rs keeps UPDATE_ACTIONABLE_CEILING=5_509 (re-measure pending). The LFT/Turtle_TransmogUI rows benilla.toc named off the player's install now come from the chain's own FrameXML.toc via the new core loader.
84 lines
5.4 KiB
Markdown
84 lines
5.4 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, its FrameXML extracted to a folder, and the maintainer's runtime capture of
|
|
the reference client's `_G`, 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`. Two gates hold the line.
|
|
`crates/benilla-ui/src/script/tests/reference_surface.rs` fails if the engine puts a global 1.12
|
|
does not have in a bare VM and nobody wrote down why, with no prefix excusing an engine name.
|
|
`crates/benilla-app/src/ui_script/surface_gate.rs` fails if the production load, the core and
|
|
benilla's layer, adds any global past 1.12 other than the layer's own `Benilla`-prefixed names, or
|
|
any widget method.
|
|
|
|
## `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, their extents and the
|
|
disassembly are the maintainer's, 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).
|