Data: how the game gets its tables
Purpose
Section titled “Purpose”Every table-driven spec reads excel records. This subsystem says which bytes those are: which archive a file comes from, which form of a table is loaded, how a record is addressed, and how a code or a name in one table becomes a record index in another. It runs once, at startup, before any game is created. It draws no random numbers.
| File | Covers |
|---|---|
| excel.md | MPQ precedence and file lookup, .bin vs .txt, record addressing, code and name links, the treasure-class index space, monster references, string-table keys (stored indices), cell values, the .txt compiler |
| calc.md | the formula bytecode in *code.bin: encoding and opcodes, the .txt compiler, the evaluator CALC_Eval, the skills/missiles/items contexts, their function tables and variables |
| strings.md | string tables at run time: load order and condition, index → text, key → index, hash probing, UTF-8 → UTF-16, the 5382 rule, fallbacks and fatal paths |
Per-table record layouts are not specs. They live, one doc per table, and the container formats.
Data flow
Section titled “Data flow”-
[C] Every excel table is read from its compiled
.bin; no.txtis parsed in a stock run. -
[C] File lookup searches the open MPQs by descending priority, so for excel data
patch_d2>d2exp>d2data: a kept log reads each kind of file the archives hold with different bytes with 0 mismatches on that order, and with any other copy it fails. Loose files are consulted only under-direct, and then before every archive: the loose run’s three loose files were never read, and the direct run, with only the switch changed, read all three from disk. -
[I] The optional
d2kfixupandd2deltawould sit betweend2expandd2data(excel § A A1, A2). Our install ships neither, so no run shows their place. -
[C] The live treasure-class table is
treasureclassex.TreasureClass.txtis never loaded. -
[C] Each loaded
.binholds fixed-size records whose stride is the one the game’s consumers use, for all 86 loaded tables.
Entry points
Section titled “Entry points”| When | Function | Tag |
|---|---|---|
| Startup, before the excel load | MPQ_OpenCoreArchives, MPQ_OpenGameArchives |
[C] |
| Startup, all tables | DATATBLS_LoadAll (fixed call sequence, one loader per table) |
[C] |
| A consumer resolves an item code | ITEMS_GetByCode → EXCEL_FindCode |
[C] |
| A TC name is resolved (at load) | EXCEL_FindName on g_TCLink, called from TC_ParseItemCell, TC_BuildChestTable (from TC_LoadAll) and, under -txt, the .txt parser |
[C] |
- [C] The four rows are logged in the H3b runs: the 12 archive opens before the first string-table and excel load,
one
DATATBLS_LoadAllcall with the same 73 table loads in the same order in every stock-mode run, 1 147 item-code calls that return the code’s combined position, and 3 728EXCEL_FindNamecalls on the TC link that return the TC index of the name (−1 for the 6 names that are no TC). In the stock run no TC name lookup ran in play. - [I]
TC_GetByName, the name → TC wrapper, is dead code: no call, jump or pointer in the image names it, and its breakpoint had no hit in the seven runs. A computed call target is not excluded.
Downstream
Section titled “Downstream”items/tcconsumes the TC index space and theItemNresolution in excel.md.monsters/*anddrlg/*indexmonstats,levelsandleveldefsby record position.data/stringstakes over at the string index stored in the records (excel.md, then strings.md).- data/calc takes over at the
*code.binoffsets stored in formula columns.