Game data: tables, strings and formulas
Much of what Diablo II does is driven by tables: which monsters a level can have, what a
treasure class drops, how much a skill does. The game keeps that data in “excel” tables (Levels,
MonStats, TreasureClassEx, Weapons and about eighty more), in three string tables that hold the names and text
shown on screen, and in small compiled formulas that some table cells carry instead of a plain number. This page explains how the game finds and loads
those files, how a record is addressed, how one table points at another, how a stored number becomes a name on
screen, and how a formula is run. It restates four specs: the data overview,
excel tables, string tables and
calc formulas. The loading happens once, at program start, before any game exists, and it
draws no random number; formulas are evaluated later, when the game needs a value, and only a formula’s rand can
draw (below).
The big picture
Section titled “The big picture”The diagram is a simplified copy of the data flow and the excel algorithm; the text below is what counts.
Which archive a file is read from
Section titled “Which archive a file is read from”The game’s data sits in its MPQ archives. At start-up the game opens them and keeps them in a list sorted by
priority; a lookup walks that list and the first archive that has the file wins. For the table files this gives the order
patch_d2, then d2exp, then d2kfixup, then d2delta, then d2data. d2exp is opened whenever it exists,
even for a classic game, so classic and expansion games read the same tables.
Loose files on disk are only looked at when the game runs with -direct (or when no archive is open at all), and
then they beat every archive. In a
normal run a loose file never overrides an archive. This is confirmed in runs that watched the game from before
its start-up code: the archive opens, the sorted list after each open and every file lookup match these rules, a run
with loose files but no -direct read none of them, and the same kind of files with -direct were read from disk.
Only the place of the two optional archives in the middle of the list (the install has neither) and the case with no
archive open (no lookup ran before the first open) are read from the code. The video archive is opened later, when a cinematic is played, and goes to the front of its priority group.
The game reads the .bin, not the .txt
Section titled “The game reads the .bin, not the .txt”Every table exists in two forms: a tab-separated .txt source and a compiled
.bin, which is a 32-bit record count followed by fixed-size records. The game always loads the .bin; in a
normal run no .txt is parsed at all. This is confirmed: the in-memory “parse the text” path is dead, and for all
86 loaded tables the record size the game’s code uses matches the file.
The -txt option compiles the .txt files and writes fresh .bin files to disk, and then loads the .bin
through the normal lookup. Without -direct the game never sees the disk copy, so -txt alone changes nothing;
only -direct -txt makes the game run on edited text. Both are confirmed in a run: with -txt alone every table
loaded was the archive’s copy, and with -direct -txt every table read after the compile came from the freshly
written files.
A few consequences that a modder or reimplementer would trip over:
TreasureClass.txtis never loaded. The live table isTreasureClassEx(confirmed).- Five tables (
automagic,RarePrefix,RareSuffix,inventory,PlrMode) have their.binand their newest.txtin different archives. The game’s own compile of that.txtgives the shipped.binbyte for byte, so it makes no difference which one is taken (confirmed). - A few tables ship and are never loaded at all (confirmed for
cubemodandcubetype), and some small code-list tables are loaded only under-txt, for the compiler. One of them,hitclass, is still read whole at every start by another loader (confirmed). Three of these code lists, the body locations, the player classes and the item and skill events, are only index spaces in a normal run: the other tables store a row number (location 0 to 10, class 0 to 6, event 0 to 12) and the code uses it as a plain number (read from the code). - The
soundstable is not loaded in a normal run. With sound off no sound file is read at all (confirmed); with sound on, the client readssounds.txtas text, and only-txtloadssounds.bin(read from the code). - Some tables load at every start but carry no game rule. Read from the code:
MonItemPercentis read by nothing, so it changes no drop;Composit,MonSoundsandAutoMapare read by the client’s drawing and sound only; ofOverlaythe server reads only the row count, as a bound on an overlay number;Arenafeeds a per-player score in every game that no core rule reads. OfSkillDesc, the server reads the skill-tree page, which decides whether a ”+ to a skill tab” item counts for that skill.
Records are positions
Section titled “Records are positions”Record i of a table is simply the i-th fixed-size record after the count. A record number is a position in the
.bin, not a line of the .txt. The difference
comes from the expansion marker: a .txt row whose first field is Expansion has no record, so
every record after it sits one lower than its text row. leveldefs is the second half of Levels: its record i
describes the same level as Levels record i, and it has no count of its own (the shared count is read from the
code).
How one table points at another
Section titled “How one table points at another”Tables refer to each other in three ways; the first two go through a lookup object, a link:
| Kind | Example | Lookup | Case |
|---|---|---|---|
| 4-character code | item code hax |
sorted list of codes, binary search | sensitive |
| name | a treasure class name | name tree, first 31 characters | insensitive |
| stored position | a monster in Levels mon1 |
none: the number is used directly | — |
Items. Weapons, armor and misc are loaded into one combined array, in that order. The item index used everywhere else is the position in that array: with the shipped counts, weapons are 0–305, armor 306–507 and misc 508–658. An item code is its four bytes read as a number, compared unsigned and case-sensitively. If two records had the same code, the second would be filed under the next free number and become unreachable by its own code; the shipped tables have no duplicates, so this never happens on stock data.
Names. Name lookups lowercase the ASCII letters and compare only the first 31 characters. When two records share a name, a lookup returns the first one registered.
These lookups are confirmed. Item codes resolve to their combined position in over a thousand logged calls, and the code and name lookups were run under an emulator against a model (the unsigned compare, the case rules, the 31-character cut, duplicate codes). That the duplicate-code rule never fires on stock data has nothing to observe.
Treasure classes share one numbering
Section titled “Treasure classes share one numbering”Every stored treasure class (TC) reference, such as a monster’s TreasureClass1, uses one
index space built at load. This numbering is confirmed
against every non-blank TC cell of MonStats:
| TC index | Meaning |
|---|---|
| 0 | the empty TC: a stored 0 means “no TC” |
| 1 to 160 | automatic TCs built from item types (5 types × 32 levels: 3, 6, … 96) |
| 161 + r | TreasureClassEx record r (852 records, ending at the first empty name; the count is read from the code) |
While loading TreasureClassEx, the game also resolves each ItemN cell. A name of up to four characters is tried
as an item code first; failing that, it is looked up as a TC name, then as a unique item name, then as a set item
name; a name that matches nothing is dropped. So a short TC name that equals an item code means the item. A unique or
set entry keeps two numbers: the base item of the named row and the row itself, which item creation later uses to make
that exact unique or set item (read from the code, excel G4). The loader
stops reading a row’s items at the first empty ItemN, so an item after a blank cell is ignored; a
Picks of 0 becomes 1; and a cell with a probability below 1 is skipped. A replay of the logged
drops confirms the numbering, the item-code-first rule and the resolution of every logged cell; the three rules just
named, a short name that is both an item code and a TC name, the unique and set steps and a name that ends at an
inner quote have no stock case and are read from the code.
The automatic TC of an item type for level L (named after the type code and L, such as bow3) takes the non-quest,
spawnable items of that type whose level is above L − 3 and at most L, each weighted by the rarity of the item’s own
type, with one pick and no upgrade (confirmed in the logged drops). “Of that type” counts an item whose own or second
type is that type or descends from it through the item types’ parent columns; that the build uses this test is read
from the code. After the load the game looks up 45 chest TC names
(Act 1 Chest A and so on) for the objects’ chests; the lookups are confirmed in the start-up runs, and where it
keeps the result is read from the code.
Monster references and the off-by-one
Section titled “Monster references and the off-by-one”A stored monster reference (Levels mon1, MonStats minion1 and the like) does not hold a MonStats record number.
It holds a distinct-Id ordinal: the position of that monster’s Id among the distinct Ids of
MonStats. The game then uses that number directly as a record position.
The two agree until MonStats repeats an Id. It does once: cr_lancer8 appears at records 617 and 723. From
record 724 on, ordinal and position differ by one, so a reference to one of those monsters reaches the record
before it. In the shipped data this affects three cells of Act 5 - Pandemonium 3 (mon1, nmon1, umon1),
which name overseer6 but reach the second cr_lancer8. The stored ordinals are confirmed by the data, and that
the game uses them as positions is confirmed for the level’s monster pool: that level’s pool held
class 723 in every logged game. A scan of every reader of MonStats in the code finds none that looks a monster up by
its Id (read from the code). Whether such a monster is ever seen in play is left to the monster specs.
What a stored cell means
Section titled “What a stored cell means”A short guide to the values inside a .bin record, all checked against every cell of the documented tables:
| Field kind | Stored value | Blank cell |
|---|---|---|
| integer | the number, cut to the field width with no range check (999 in a byte is 231) | 0 |
| 4-character code | four bytes, space-padded | four spaces |
| reference to another table | the target’s record index, first match | the target’s empty-key row if it has one, else −1 |
| item-type reference | as above, key cut to 4 characters (staff finds staf) |
0, which is the None row |
| TC reference | TC index (TreasureClassEx row + 161) | 0 |
| string key | string index | 5382 |
| formula | offset into a formula pool | −1 |
The .txt compiler that produced these values (header matching, defaults for a missing column, the quirks above) is
described in excel § J. Only a reimplementation that compiles
.txt itself needs it.
String tables: from a number to text
Section titled “String tables: from a number to text”Records and code name a text by a 16-bit string index. Three string tables of the chosen language hold the texts, each with its own base:
| Index | Table | Entry |
|---|---|---|
| 0–9999 | string.tbl |
the index |
| 10000–19999 | patchstring.tbl |
index − 10000 |
| 20000 and up | expansionstring.tbl |
index − 20000 |
The game loads string.tbl, then patchstring.tbl, then expansionstring.tbl whenever the expansion archive
exists, for a classic game too. This is confirmed in a run: a classic session showed character-select text from
the expansion table. Every
text is converted from UTF-8 to 16-bit characters once, at load.
The lookup is by entry position. A language whose table has other entries would show other text for the same
stored index, and the stored indices are the English ones. The language comes from the first byte of the file
data\local\use. The start-up runs confirm it: the shipped byte
0 gave English, and the shipped Russian file’s byte 11 made the game look for Cyrillic fonts, fail to load the font
map and exit before reading any string table. A byte above 13 becomes English, and a byte of exactly 13 reads past
the language table (confirmed under an emulator) and would crash the load; both need an edited file and are read
from the code. Only English ships the expansion table, so another language whose fonts load would still crash at
that table (read from the code). Two fallbacks, an expansion index with no expansion table and an entry past the end
of a table, cannot be reached on a stock install; what they do is confirmed by running the game’s own lookup under
an emulator.
String keys: from a name to a number
Section titled “String keys: from a name to a number”Some code, mostly table loaders, looks a text up by its string key, an ASCII name such as
GloomUM:
The search order is patchstring, then expansionstring, then string, and the match is exact. Each
table is a hash table searched by walking from a home slot; a miss always walks the table’s whole probe limit (1 179
nodes in the English patchstring, for example). When a key occurs twice in one table, the lowest entry wins. A key found nowhere
returns 0 with a placeholder text: the key followed by the suffix ” -not xlated call ken w”, minus its last
character, so funeralpire gives “funeralpire -not xlated call ken ” with a trailing space. All of this is
confirmed in a run that logged the game’s key lookups, except that the match is case-sensitive: no logged key differs
from a table’s key only in case, so that part is read from the code. One quirk is confirmed under the emulator: entry 0 of
string.tbl cannot be told apart from “not found”, since both give 0.
When the .txt compiler turns a string-key cell into a stored index, it replaces 0 (blank or unknown) by 5382,
the string.tbl entry named dummy.
That is why blank name cells in the shipped .bin files hold 5382. One cell of the shipped files breaks the rule:
the uberandariel monster’s name Lilith exists in the English patchstring table, yet its cell stores 5382. The
game’s own compiler stores the key’s index there (confirmed with a compile run), so the shipped file was probably
made against string tables that lacked the key.
Names on items and monsters
Section titled “Names on items and monsters”Name columns hold stored string indices: MonStats NameStr, SuperUniques Name (the names of
superuniques), the UniquePrefix name words and Weapons namestr are examples. Showing one of those names is an index lookup.
Rare names take a slightly different path
(strings § D, Rare names). The .bin stores no index for
them. A run that hovered four rare items confirms the load-time lookup and the two shown indices; the fallbacks for
a 0 index and a missing record are read from the code. When the rare-name tables are loaded, each record’s name key is looked up and the index kept. When the
client shows a rare item, it takes the item’s two rare-name ids, finds each record and shows the text of each stored
index; if an index is 0, it shows the raw key in parentheses instead, and a missing record leaves its word empty. The two words are then put into the string
RareFormat as its first and second arguments, the way the magic name line uses MagicFormat (prefix, base name,
suffix). The run shows the line using RareFormat; the order of the arguments is read from the code. In the
shipped English table RareFormat is %0 %1 (checked in the data), so
an English rare name is the first word, one space, the second word. The order and the separator come from the string
table, so another language may change them. This rests on %0 and %1 standing for the first and second argument;
the code that substitutes them is not read yet.
One loader shows how a key lookup can silently fail: the gems table loader builds a key from bytes that, in this version, hold the gem’s compiled item index rather than its code text, so the lookups miss (the run saw 68 such keys) and every gem stores 0 there. This is confirmed: the 68 logged keys are exactly those bytes of the 68 gem records.
Calc formulas
Section titled “Calc formulas”Some cells hold a calc formula rather than a number: a skill’s damage or duration, a number in a
skill description, a missile’s synergy, a potion’s duration and strength. In the shipped data these are already
compiled into postfix bytecode, kept in four pools (skillscode, skilldesccode, misscode, itemscode), and the
record stores an offset into its pool, or −1 for a blank cell, which evaluates to 0 (that last step is confirmed by
running the game’s own code under an emulator). The spec describes the machine that runs the formulas, not
what each one means. One link to combat is named, from the code: the ToHitCalc result of a player skill is the
attack-rating percent its melee hit passes to the hit test (see the combat page).
The code. Postfix means operands come before their operator: (lvl < 4) ? lvl : (2+lvl/3) becomes “lvl, 4, <,
lvl, 2, lvl, 3, ÷, +, ?:, end”. Each step is one opcode byte,
sometimes followed by a constant, a variable number or a function number.
The evaluator runs those bytes on a stack of 32-bit integers. Three points matter for an exact copy, all confirmed in a run of 44 529 evaluations with no mismatch:
- Both branches of
?:are computed. The ternary is just an operator over three values already on the stack, so every variable read and function call in the unused branch still happens. - Division truncates toward zero, as in C. A zero divisor gives 0 rather than a crash, confirmed under the emulator. One division still crashes the game: the smallest 32-bit integer divided by −1. That is read from the code only, since an emulator cannot show a crash, and only an edited formula can reach it.
- Evaluation stops at the end byte, and also at the byte the compiler emits for an unclosed
(; stock Fire Wall ends that way.
The rest of the evaluator, which no stock formula reaches, is confirmed by running the game’s own code under an
emulator against a model: the opcodes the compiler never emits, comparisons other than < and >, the power operator,
overflow (it wraps), a stack of 64 values that drops any further push, and a pop from an empty stack, which gives 0.
Contexts. A formula runs with a context: a skill formula with the unit, the skill
and its level; a missile formula with the missile, its owner and a level; an item formula with the unit that uses
the item and the item itself. Variables
are the rows of SkillCalc or MissCalc (lvl, par1…, ln12 and so on). Item formulas have no variables
(confirmed under the emulator), and the stock ones are all constants. The functions are min max rand skill miss stat sklvl for skills, a shorter list for
missiles and items. Values that depend on the unit’s state (its skill levels, its stats, elemental damage) are inputs
the rest of the game supplies. The skills table of functions is confirmed in play, and the missile and item tables
by the run’s logs with the tables in the program file; min, max and rand of all three tables, the missile
variables (except the ones that read damage) and the missile context are confirmed under the emulator. So are the
skill variables no stock formula reads, except five that read the unit’s state: a skill’s mana cost, for example,
shifts by the table’s manashift masked to its low 5 bits. Which game functions call the missile and item formulas
is confirmed: the run’s calls return into the missile elemental-damage functions and into the potion-use function, read as
code, for a stamina, antidote or thawing potion. That the item context’s second value is the used item is read from
the code; no stock formula reads it.
rand(a, b) is the one place a formula draws: one draw on the unit’s seed,
a + Range(b − a + 1), or no draw when a ≥ b. In the missile context the
code passes a value on the stack instead of a unit seed, so that draw advances no game seed. The functions
themselves are confirmed under the emulator; which unit’s seed rand draws on when a monster actually casts the
one stock skill that uses it was not seen in play.
Compiling. Only -txt compiles formulas. The
compiler folds a formula with no variables and no function calls into one constant, fails on some text a permissive
parser would accept (a cell holding one space, min(-1,lvl), two minus signs in a row as in - -5), and then stores
−1, so the formula yields 0. It also fails past 64 pending operators or 1 024 bytes of output. All of this is
confirmed, the space on a stock cell and the rest under the emulator. Two equal formulas are stored twice, in record
order and, within a record, in the order of the columns in the text file, then the formula columns the file lacks,
which store −1 (confirmed under the emulator).
Worked examples
Section titled “Worked examples”Excel references, copied from the excel worked example (values from the
shipped .bin files):
- MonStats record 0 (
skeleton1) hasTreasureClass1= 430. Since 430 ≥ 161, that is TreasureClassEx record 430 − 161 = 269, namedAct 1 H2H A. Its runtime index is 430, and a name lookup ofACT 1 H2H Aalso returns 430, because names ignore case. - Levels record 135 (Act 5 - Pandemonium 3) has
mon1= 723. The.txtnamesoverseer6, which is record 724; record 723 is the secondcr_lancer8, and that is the record the game uses. - The weapon code
haxis stored as the bytes68 61 78 20, the number20786168in hex. It is weapons record 0, so a code lookup returns item index 0. - TreasureClassEx record 0 is
Gold, Picks 1,Item1=gld(three characters, so tried as an item code first); its runtime index is 161.
A key lookup, copied from the strings worked example, as logged in
a recorded game. Looking up the key of Amianthus:
| Step | Table | Home slot | Nodes examined | Result |
|---|---|---|---|---|
| 1 | patchstring | 961 | all 1 179 | miss |
| 2 | expansionstring | 34 | 3 (Shocking, Consecrated, then of Amianthus) |
entry 925 |
| — | string | not searched | — | — |
The index is 20000 + 925 = 20925, and the text is of Amianthus. In the same example, index 21796 shows
CHARACTER (expansionstring entry 1796, logged in a classic game with the expansion archive present), and index
5382 shows an evil force (the dummy entry, also logged once).
A formula, copied from the calc worked example: Raise Skeleton’s
petmax, (lvl < 4) ?lvl:(2+lvl/3), evaluated at skill level 3 (logged 52 times, result 3):
| # | Action | Stack after |
|---|---|---|
| 1 | read lvl → 3 |
3 |
| 2 | push 4 | 3 4 |
| 3 | 3 < 4 → 1 | 1 |
| 4 | read lvl → 3 |
1 3 |
| 5 | push 2 | 1 3 2 |
| 6 | read lvl → 3 |
1 3 2 3 |
| 7 | push 3 | 1 3 2 3 3 |
| 8 | 3 ÷ 3 = 1 | 1 3 2 1 |
| 9 | 2 + 1 | 1 3 3 |
| 10 | else 3, then 3, condition 1 → then | 3 |
| 11 | end: return 3 |
The game read lvl three times although it dropped the else-branch. The description copy of the same formula at
level 4 takes the else-branch, 2 + 4 ÷ 3 = 3, also logged as 3.
What is not known yet
Section titled “What is not known yet”From the open questions of excel, strings and calc:
- The place of the two optional archives in the search order is read from the code only; the install has neither.
- Whether anything reads two MonStats padding bytes during a game is open; nothing writes them between the load and the end of a game.
- The string-table fatal checks are read from the code and unreachable on a stock install; the other languages’ font
maps are not read; the substitution of
%0,%1in the rare and magic name lines is not read. maxandrandwere checked under an emulator but not in a live monster cast; the missile variables that read damage, and five skill variables that read the unit’s state, were not checked; the item context’s second argument (the used item) is read from the code and no stock formula reads it; hovering over the potions of one run evaluated nothing, but which items would evaluate a formula on a hover is not read; the crash on the smallest integer divided by −1 cannot be shown under an emulator.
Where to read more
Section titled “Where to read more”- The specs: data overview, excel tables, string tables, calc formulas.
- The glossary for TC index, item index, string index and key, and calc formula.
- Related wiki pages: randomness for
randand seeds; items, monsters and levels for what the game does with these tables.