Dungeon Hack — technical documentation

Reverse-engineering notes on Forgotten Realms: Dungeon Hack (SSI / DreamForge Intertainment, 1993) and the AESOP/16 engine it runs on.

This is a documentation project. The goal is to describe how the game works — its file formats, its object system, its bytecode, its engine API and its procedural dungeon generator — in enough detail that someone else could write a reader, a viewer or an interpreter. There is no port, no reimplementation and no plan for one.

No game data is distributed here. The repository contains prose, tables derived from the game's own symbol dictionaries, and Python tools that you point at your own legally obtained copy of the game.

---

What Dungeon Hack turned out to be

Not one program but three, plus an archive that holds the actual game:

• AESOP.EXE — the AESOP/16 Runtime Host Interpreter, a 32-bit stack VM by Miles Design, exposing 165 native calls, 88 bytecode opcodes, and nothing resembling game logic.
• HACK.RES / HACK.TBL — a 6.8 MB archive holding 334 compiled classes, 1 128 strings, 632 bitmap sheets, 146 sounds, 47 palettes and 3 fonts. Every rule of the game is compiled script in here, not code in an executable.
• MAZE.EXE — a standalone "Random Dungeon Generator v1.0/386" by Event Horizon Software, which reads twelve parameters and writes the whole dungeon to disk as flat files before the game ever sees it.
• HACK.BAT — the state machine that drives menu → generate → play → menu.

The archive shipped with its complete symbol tables: every resource name, every source asset path, every engine call name and every message name. That is why this documentation can be as specific as it is.

Contents

1. System architecture	the three executables, the boot chain, the two-phase loop, memory model
2. The AESOP/16 resource container	.RES / .TBL layout, record format, the paginated index, the five dictionaries
3. The AESOP object model	classes as resource triples, instance layout, imports and link-time fixups, messages, the class tree
4. The kernel API	what the 165 native calls tell you about the engine
5. Asset formats	bitmap sheets, fonts, palettes and light ramps, sound, text
6. The dungeon generator	MAZE.EXE, its twelve parameters, its outputs, the vocabulary it shares with the script
7. Runtime files	the SAVEGAME directory, automap state, high scores, save/restore
8. The AESOP/16 bytecode	the 88-opcode instruction set, how it was recovered from the interpreter, and what the decompiled game looks like
9. Open questions	what is not known, with the next experiment for each

Generated reference tables:

• reference/kernel-calls.md — all 165 engine calls, grouped
• reference/messages.md — all 616 message ids and how many classes handle each
• reference/classes.md — the full 334-class hierarchy
• reference/opcodes.md — all 88 bytecode instructions with operand forms and stack effects

Tools

Python 3, standard library only.

# container
python tools/aesop_res.py info    /path/to/HACK.RES
python tools/aesop_res.py list    /path/to/HACK.RES --json inventory.json
python tools/aesop_res.py dicts   /path/to/HACK.RES --which 3
python tools/aesop_res.py extract /path/to/HACK.RES "Main Base Palette" -o pal.bin
python tools/aesop_res.py dumpall /path/to/HACK.RES -d out/

# object system
python tools/aesop_class.py tree     /path/to/HACK.RES
python tools/aesop_class.py show     /path/to/HACK.RES dagger
python tools/aesop_class.py classes  /path/to/HACK.RES
python tools/aesop_class.py messages /path/to/HACK.RES

# bytecode
python tools/aesop_disasm.py opcodes
python tools/aesop_disasm.py verify /path/to/HACK.RES
python tools/aesop_disasm.py class  /path/to/HACK.RES "scrying glass"
python tools/aesop_disasm.py list   /path/to/HACK.RES

# regenerate reference/
python tools/gen_reference.py /path/to/HACK.RES -o reference

aesop_res.py also works on OPEN.RES, the intro archive.

Confidence

Each format is marked in its chapter. In short:

Verified — parses every instance with zero anomalies	container and index, record headers, the five dictionaries, class headers, import/export tables, the 88-opcode bytecode (334/334 classes, 83 399 instructions), fonts, palettes, bitmap container, high-score table, automap file shape
Established but incomplete	bitmap pixel encoding (terminator, row structure and markers known, grammar not), report query codes (2 of ~11 identified), VISIBLE.DAT flag bits
Not started	generated dungeon files, SETTINGS.DAT, the interpreter's message dispatcher and cache
Inferred from strings only	exit-code state machine, resource type 0x20 = resident, save/restore flow

Provenance

Work was done against a GOG release of Dungeon Hack (English, v1.0, dated 11/08/93 in README.TXT). Findings should hold for the original floppy release; version-specific details are flagged where they matter.

Licence

Documentation and tools in this repository: MIT.

Forgotten Realms, Dungeon Hack, AESOP and all game data are the property of their respective owners. Nothing here is affiliated with or endorsed by them.