DRLG overview: act → level → room, generator dispatch and room-creation order
Purpose
Section titled “Purpose”Given an act and a level id, this spec says how the game turns the level seed into DRLG rooms: the
two dispatches on Levels.DrlgType, every draw each generator makes on the level seed, the order in
which rooms are created (each creation is one level draw, so the order fixes every room’s seed), and
how a preset’s DS1 file is chosen. The maze generator that runs inside step 9 is specified in
maze.md, and the act’s level links, the warp slots and the warp points built after every level
are in warps.md. The outdoor generators that run inside step 7 (the act layouts, the border pass,
the placements and the file rotation) are specified in outdoor.md. The preset-unit drop rolls, which also draw on the
level seed, are specified in preset.md. What happens when a
room is activated (its tiles and the k room-seed draws) is in room-tiles.md, and the active room’s
collision grid, its logic regions and the spawn position tests are in collision.md. Which rooms
are active, when a room is released, and how its saved units are restored when it comes back is in
lifecycle.md.
Primitives (Step, Range, RangeB, Init) are those of rng. The act and level
seeds are defined in rng/seeds steps 3–5.
Entry points
Section titled “Entry points”| When | Function | Tag |
|---|---|---|
| Act created (server and client copy) | DRLG_ActCreate |
[C] |
| Level record created and seeded | DRLG_LevelCreate |
[C] |
| Level built (rooms created), lazily, on first need after each load | LevelInit |
[C] |
| Maze level: create / build | MazeLevelCreate / MazeLevelBuild |
[C] |
| Preset level: create / build | PresetLevelCreate / PresetLevelBuild |
[C] |
| Outdoor level: create / build | OutdoorLevelCreate / OutdoorLevelBuild |
[C] |
| One DRLG room created (one level draw) | DRLG_RoomCreate |
[C] |
| Level unloaded (rooms and per-build state freed) | LevelUnload |
[C] |
| DRLG room activated (tiles, k, active room) | RoomActivateB → DRLG_RoomActivate, see room-tiles.md |
[C] |
Inputs
Section titled “Inputs”Tables
Section titled “Tables”| Anchor | Used for |
|---|---|
Levels.txt:DrlgType |
both dispatches: 1 maze, 2 preset, 3 outdoor (leveldefs +0x30) |
Levels.txt:LevelType |
the level type (level +0x1C0): outdoor room DT1 mask, maze file-rotation base |
Levels.txt:SubType, Levels.txt:SubTheme |
LvlSub records rolled for each outdoor room (leveldefs +0x38, +0x3C) |
LvlPrest.txt:LevelId |
LvlPrestByLevel: the first record whose LevelId is the level’s id |
LvlPrest.txt:Def |
LvlPrestByDef: the record of a preset def |
LvlPrest.txt:Files |
operand of the file-index draw (+0x40) |
LvlPrest.txt:File1 |
File1..6 (+0x44 + 0x3C·i): the DS1 of index i |
LvlPrest.txt:SizeX, LvlPrest.txt:SizeY |
preset instance size, when both are non-zero (+0x28, +0x2C) |
LvlPrest.txt:Scan, LvlPrest.txt:Pops |
map-scan gate before a preset’s rooms are made (+0x34, +0x38) |
LvlPrest.txt:Dt1Mask |
every preset room’s DT1 mask (+0x1AC), see room-tiles.md |
LvlMaze.txt:Level, LvlMaze.txt:SizeX, LvlMaze.txt:SizeY |
the first maze room’s size |
LvlSub.txt:Prob0 |
Prob[SubTheme] of each SubType record in the outdoor room roll (+0x11C) |
LvlSub.txt:Dt1Mask |
OR-ed into an outdoor room’s DT1 mask when its record is picked (+0x48) |
Runtime state
Section titled “Runtime state”Offsets are byte offsets into the owner.
| State | Type | Owner offset | Source |
|---|---|---|---|
| level seed base | u32 |
act +0x470 |
rng/seeds step 3b |
| level seed | Seed |
level +0x1C4 |
step 1, step 2 |
level id, DrlgType, level type |
u32 |
level +0x1D0, —, +0x1C0 |
leveldefs |
| preset level data: file index | i32 |
level data +0x04 |
step 3 |
| preset instances | list, prepended | level +0x1B0 |
step 4 |
| maze file-rotation counters | list of {Def, Files, c, next}, 0x10 bytes each |
level +0x1CC |
step 9 |
| level’s rooms | list, prepended (next at room +0x24), count +0x08 |
level +0x10 |
step 5 |
| DRLG room first draw | u32 |
DRLG room +0x04 |
rng/seeds step 5 |
| DRLG room seed | Seed |
DRLG room +0x14 |
rng/seeds step 5 |
| DRLG room type | u32: 1 outdoor, 2 preset |
DRLG room +0x48 |
step 5 |
| DRLG room DT1 mask | u32 |
DRLG room +0x50 |
steps 6, 8 |
| preset instance | 0x58 bytes: +0x04 file index, +0x08 record, +0x0C DS1, +0x3C client-objects flag |
— | step 4 |
| outdoor room SubType pass | +0x64 type, +0x68 theme, +0x6C mask |
OutRoom (DRLG room +0x20) |
step 8 |
Constants
Section titled “Constants”| Name | Value | Anchor | Tag |
|---|---|---|---|
| preset room block | 8 × 8 cells | PresetRoomsCreate |
[C] |
| maze room single-room limit | 12 × 12 | MazeLevelRooms |
[C] |
| outdoor room DT1 mask by level type, checked types | 2 → 0x44103; 16 → 0x1; 21 → 0x4; 31 → 0x11 |
OutdoorRoomsCreate |
[C] |
| outdoor room DT1 mask by level type, other types | 22, 27, 28 → 0x1; 30 → 0x11; any other type → 0 |
OutdoorRoomsCreate |
[I] |
MAZE_DEF_BASE by level type |
3 → 0x34, 4 → 0x6C, 7 → 0xA7, 8 → 0xCD, 10 → 0x101, 13 → 0x12D, 17 → 0x19D, 18 → 0x1E1, 22 → 0x2F1, 24 → 0x298, 25 → 0x2C0, 28 → 0x344, 33 → 0x3EA, 34 → 0x422, 35 → 0x41C; other types: no rotation |
MazePresetFile (switch) |
[C] |
- [C] The outdoor mask values are checked against the logged rooms for four level types: 2 in 56 Blood Moor rooms, 16 and 21 in 40 and 20 rooms, and 31 in 145 type-1 rooms of
levels 111, 112 and 117, with the
SubTypemasks ORed. No run logged a type-1 room of types 22, 27, 28 or 30, so the second row is read from the code only.
Algorithm
Section titled “Algorithm”L is the level, L.seed its seed, base the act’s level seed base. Every Range, RangeB and
Step below on L.seed is a level draw, and the level seed has no other consumer outside the
sub-generators of § Sub-generator boundaries (the maze and outdoor windows, oracles of
the first runs, now modelled) and the preset drop rolls of step 5a.
1. CreateLevel(act, id) → L: [C] Init(L.seed, (u32) (base + id)) ; rng/seeds step 4 dispatch on DrlgType: 1 → MazeLevelCreate: the lvlmaze row by level id, position ; no draw 2 → PresetLevelCreate: ; step 3 3 → OutdoorLevelCreate: allocate the 0x268-byte outdoor record ; no draw prepend L to the act's level list
2. LevelInit(L): [C] Init(L.seed, (u32) (base + L.id)) ; again, same start value L.rotations ← empty ; see step note 9 dispatch on DrlgType: 1 → MazeLevelBuild (9), 2 → PresetLevelBuild (6), 3 → OutdoorLevelBuild (7) LevelRoomStateRestore(L); LevelWarpPointsBuild(L) ; no draw; warps.md § E [C]
3. PresetLevelCreate(L): [C] P ← LvlPrestByLevel(L.id) ; fatal if none files: i32 ← P.Files L.data.idx: i32 ← (files ≠ 0) ? RangeB(L.seed, files) : −1 ; level draw iff files ≠ 0
4. PresetInstanceCreate(L, def, rect, seed = L.seed) → ps: [C] ps.def ← def; ps.rec ← LvlPrestByDef(def) n: i32 ← ps.rec.Files ps.idx: i32 ← Range(L.seed, n) ; level draw iff n ≥ 1; n ≤ 0 → 0, no draw ps.x, ps.y ← rect.x, rect.y (ps.w, ps.h) ← (SizeX ≠ 0 and SizeY ≠ 0) ? (SizeX, SizeY) : (rect.w, rect.h) ps[+0x3C] ← 1; prepend ps to L[+0x1B0] The DS1 the instance loads is ps.rec.File(ps.idx + 1).
5. PresetRoomsCreate(L, ps, flags, single): [C] 5a. PresetMapScan(L, ps): [C] room-flag grid ← flags | the seam bits of the level (warps.md § D) ; always, no draw [C] if ps.rec.Scan = 0 and ps.rec.Pops = 0: nothing more else: load File(ps.idx + 1) into ps[+0x0C]; PresetUnitDropRolls on L.seed ; preset.md steps 2a, 3; step note 5 if Scan: warp-slot, waypoint and level-point cells ; warps.md § D, no draw 5b. if single: ; one room for the whole preset R ← DRLG_RoomCreate(L, 2) over ps's rect ; one level draw else: for y0 in 0, 8, 16, … < ps.h: ; rows outer for x0 in 0, 8, 16, … < ps.w: ; columns inner R ← DRLG_RoomCreate(L, 2) at (ps.x + x0, ps.y + y0), ; one level draw size min(8, ps.w − x0) × min(8, ps.h − y0) every R: R[+0x50] ← ps.rec.Dt1Mask; R → ps (R[+0x20] preset room data) [C] DRLG_RoomCreate itself: rng/seeds step 5 (Step(L.seed); R.seed ← Init(L.seed.low); Step(R.seed); R[+0x04] ← R.seed.low)
6. PresetLevelBuild(L): [C] ps ← PresetInstanceCreate(L, LvlPrestByLevel(L.id).Def, L.rect) ; step 4: one draw iff Files ≥ 1 if L.data.idx = −1: L.data.idx ← ps.idx else: ps.idx ← L.data.idx PresetRoomsCreate(L, ps, flags 0, single false) if L.id ∈ {40, 103, 109}: act[+0x488](…) ; town callback [C] else if act[+0x454] ≠ 0 and ps.rec.AutoMap ≠ 0: [C] LevelInit every linked level not yet built; activate this level's rooms
7. OutdoorLevelBuild(L): [C] cw: i32 ← L.w ÷ 8; ch: i32 ← L.h ÷ 8 ; signed, toward zero; four cw × ch cell grids outdoor generator on L.seed: VertexRingBuild, OutVertsToCells, then the act's generator (L.id = 134 → the Act II one, else by act index) ; outdoor.md § A–L OutdoorRoomsCreate(L) ; step 8
8. OutdoorRoomsCreate(L): [C] mask: u32 ← outdoor room DT1 mask of L's level type (Constants) for cy in 0 ..< ch: ; rows outer for cx in 0 ..< cw: ; columns inner c: u32 ← cell(cx, cy) ; the outdoor generator's output (outdoor.md § B) x: i32 ← L.rect.x + 8·cx; y: i32 ← L.rect.y + 8·cy ; cell position [C] (11 516 out rooms) if c & 0x200: ; preset anchor cell def ← grid2(cx, cy) if def ≠ 0: ps ← PresetInstanceCreate(L, def, {x, y, 0, 0}) ; one draw iff Files ≥ 1 ps.idx ← (c >> 16) & 0xF ; overwrites the draw PresetRoomsCreate(L, ps, flags = grid0(cx, cy), single false) else if not (c & 0x100): OutRoomCreate(L, (x, y), 8 × 8, mask) ; 8a ; c & 0x100 without 0x200: covered by a preset, nothing 8a. OutRoomCreate: [C] R ← DRLG_RoomCreate(L, 1) ; one level draw R[+0x50] ← mask LvlSubRoll(R): ; on R.seed, after R's own creation draws t ← Levels[L.id].SubType; th ← Levels[L.id].SubTheme pass: u32 ← 0 if t = −1 or th = −1: skip the loop ; no draw: [C] with both −1 (1636 calls), ; [I] with only one −1, no stock case (step note 8) rec ← the first LvlSub record with Type = t for i ← 0, 1, …, while records rec+i have Type = t: Step(R.seed) ; room draw, one per record r: u32 ← R.seed.low mod 100 ; unsigned if (i32) r < LvlSub[rec+i].Prob[th]: ; signed compare pass |= 1 << i; R[+0x50] |= LvlSub[rec+i].Dt1Mask OutRoom +0x64, +0x68, +0x6C ← t, th, pass
9. MazeLevelBuild(L): [C] R0 ← DRLG_RoomCreate(L, 2) ; one level draw R0.size ← (lvlmaze.SizeX, lvlmaze.SizeY), centred in L.rect; link R0 to L maze generator on L.seed and the maze rooms' seeds ; maze.md: creates and removes maze rooms [C] for M in L.rooms, list order (newest first; M.next read before the call): MazeLevelRooms(L, M) ; 9a 9a. MazeLevelRooms(L, M): [C] ps ← PresetInstanceCreate(L, M.def, M.rect) ; one draw iff Files ≥ 1 MazePresetFile(ps, forced = M.idx, L) ; 9b PresetRoomsCreate(L, ps, flags 0, single = (M.w ≤ 12 and M.h ≤ 12)) unit nodes of M with [+0x0C] = 1 → RoomAdjLink ; no draw [C] (393 maze builds) RoomFree(M) ; the level keeps only the preset rooms 9b. MazePresetFile(ps, forced, L): [C] if forced ≠ −1: ps.idx ← forced; return b ← MAZE_DEF_BASE[L.levelType], or return (ps.idx kept) if the type has none if b < ps.def < b + 16: ; strict on both sides if L.rotations has no node for ps.def: ; first use in this build c: i32 ← RangeB(L.seed, Files) ; one level draw (Files ≥ 1) add {ps.def, Files, c} to L.rotations node.c ← (node.c + 1) mod node.Files ; signed idiv ps.idx ← node.cStep notes:
-
The create-time dispatch makes at most one level draw (the preset level’s index). [C] (
DRLG_LevelCreate: 149 level creations)DRLG_LevelCreatealso copies leveldefs+0x34(LevelType) to level+0x1C0, its only DRLG writer; the room DT1 list and the maze rotation read the type from there. [C] (DRLG_LevelCreate,Levels.txt:LevelType: every logged copy of+0x1C0over 123 levels equalsLevelType) -
The level seed is initialised twice with the same value. Every level draw that creates rooms happens after
LevelInit’s re-seed, so the create-time draw is discarded, and the room sequence doesn’t depend on anything that ran between creation and build. [C] (LevelInit: 32 builds) A level is built lazily. When the player leaves it,LevelUnloadfrees its rooms and its rotation list, and on re-entryLevelInitruns again on the same level object. [C] (LevelUnload,RoomFree: 188 unloads, 59 rebuilds of an unloaded level object, no level built twice without an unload between) The rebuild repeats the same draws, files and rooms: in the owner’s Catacombs entry levels 35 and 36 were built three times each and level 34 twice, all identical to the model. [C] -
PresetLevelCreateusesRangeB, the second compile of the guarded range (rng step 2). WithFiles = 0the index is −1 and no draw is made. [C] -
Filesis the operand, not the number of named files.PresetInstanceCreatealways passesLvlPrest +0x40. A power-of-two operand is reduced with a mask, any other with an unsignedmod, which give the same result (rng step note 2). [C] (PresetInstanceCreate: 960 instances, each loading exactly the predicted file) An index ≥Filesarises only from an override: the level’s index (step 6), an outdoor cell’s bits 16–19 (step 8) or a maze cell’s forced index (step 9b). In the run that covered 9 of the 81 records whoseFilesand named count disagree. [C] The other 72 can only get their index through the same three overrides. [C] Neither record lookup testsExpansion. This has no stock observable: everyExpansion1 record is an Act V record, and a classic game builds no Act V level. [I] -
The map scan steps the level seed. At build time
DRLG_PresetUnitDropRollsruns fromPresetMapScanon the level seed, between the instance draw and the first room creation: one level draw per drawing unit of the DS1 (preset.md steps 2a and 3). With the rolls modelled the run replays with every seed asserted: 91 calls (52 in the five scripted logs, 39 in the owner’s Catacombs log), 2 of which drew (both in Act II), 21 244 checks, 0 mismatches. [C] When the map scan has loaded the DS1, the activation-time DS1 load skips its own rolls on the room seed (room-tiles.md step 1, preset.md step 2b). [C] The 8 × 8 split gives the Act I town (56 × 40) 35 rooms and a 24 × 24 preset 9, created rows outer, columns inner. [C] -
The seed entering the outdoor generator is the re-seeded level seed. The generator itself, from the vertex ring to the cell grids, is outdoor.md: 522 windows of 29 levels reproduced, every level-seed step checked. [C] Level 134 takes the Act II generator. [I]
-
Every embedded preset in the run was followed by the cell override, and its instance loaded that file: 914 instances, 830 with a draw and 84 with
Files = 0. The cell value, bits 16–19 included, is the outdoor generator’s output. [C]LvlSubRolldraws on the new room’s seed, right after the room’s own creation draws (rng/seeds step 5), so these draws come before the activation re-seed and are not part of k. The rolled mask and the room seed are reproduced 466 times. [C] WithSubTypeandSubThemeboth −1 the roll returns a pass mask of 0 at once, with no draw: 1636 logged calls, seed unchanged. [C] With only one of them −1 the same return is taken; aSubTypewith no record also gives 0 and no draw; the theme index is not bounds-checked. None of the three has a stock case: only level 120 has one −1 and it has no out room, no level names aSubTypewithout a record, and none has aSubThemeabove 4. [I] Each room’s position isL.rect + 8·(cx, cy); an embedded preset gets the rect{x, y, 0, 0}and its rooms’ size and position come from the preset (drlg/preset). The position changes no draw. [C] (OutdoorRoomsCreate: every one of 11 516 out rooms has its logged rect and creation order, and the level seed matches after every window) The DT1 mask it produces (the level-type value OR the picked records’Dt1Mask) equals the room’s+0x50in all 56 Blood Moor rooms. [C] -
Maze rooms become preset rooms. The maze generator works with its own rooms. Afterwards each listed maze room is converted into a preset instance, which creates the level’s real (type 2) rooms, and is freed. The seed entering the maze generator (maze.md, an oracle of the first run) is the seed after the first room’s draw; the conversion order is the room list the generator leaves, newest first. [C] (
MazeLevelBuild,MazeLevelRooms: Den of Evil, Sewers Level 1, Catacombs Levels 2–4) The generator’s room count, positions,Defs, forced indices and list order are maze.md’s; the conversion walks the list it leaves. [C] (MazeLevelBuild: 230 windows) Rotation counters are per build. The list lives at level+0x1CC, nodes are prepended, andLevelUnloadfrees it and zeroes the field, so each build starts without counters. [C] (MazePresetFile,LevelUnload: per-build counters reproduce 1648 first-use draws and 2424 rotations over 393 builds, rebuilds included;LevelUnloadfrees a non-empty list in 76 unloads) Every use, the first included, advances the counter before it is used: the first use of a def yields(RangeB + 1) mod Files. [C] (MazePresetFile: 16 first uses and 18 rotations in the scripted entries, 42 and 73 in the owner’s Catacombs entry)
Act-seed consumers
Section titled “Act-seed consumers”- [C] Before any level is built,
DRLG_ActCreateruns the per-act link setup, specified in warps.md § A–C:ActLinkInitswitches on the act index to one ofActLinkAct1,ActLinkAct2,ActLinkAct3,ActLinkAct4,ActLinkAct5, which runLevelLinkBuildand theLinkPickcallbacks on a copy of the act seed.LevelLinkBuildcreates each linked level (LevelEnsure), writes its position, writes the link value into the index of preset levels 1 and 40, and writes level 27’s index from one act-seed draw while it handles level 6 when Black Marsh ends on side 1 or 3. ThenDRLG_ActCreatecreates the act’s town level and callsLevelIniton it. Acts I, II, IV and V are reproduced (196 link builds); Act III’s jungle layout steps the act seed itself and is outdoor.md § J, reproduced. See also rng/seeds step 3d.
Outputs
Section titled “Outputs”For each built level: its DRLG rooms, linked at level +0x10 (newest first), each with its type (+0x48), rect, first draw +0x04 (which seeds it at activation), DT1 mask +0x50, and for type 2 its preset instance with the chosen file index. For outdoor rooms also the SubType pass (+0x64–+0x6C) that their activation applies. The level seed ends where the last modelled draw leaves it. [C] (LevelInit: the seed at every build’s end and the room count of every build checked)
Worked example
Section titled “Worked example”base = 015B2E77 (rng/seeds worked example). Level 8 is DrlgType 1, level type 3, so MAZE_DEF_BASE is 0x34 and defs 53–67 rotate.
| Step | Operation | Level seed after | Result |
|---|---|---|---|
| 2 | Init(base + 8) |
015B2E7F:0000029A |
|
| 9 | first maze room: DRLG_RoomCreate |
E18C3A55:0090CE8A |
room +0x04 = C176B603 |
| 9 | maze generator (maze.md, example 1) | 334AA35A:02E00A8C |
list: def 98 at (1500, 1024), def 83 at (1524, 1000), def 58 at (1500, 1000), all 24 × 24, forced index −1 |
| 9a, 4 | def 98, Files 1: Range(1) |
12CE5ECE:1564B05F |
idx 0 (a draw even though n = 1) |
| 9b | 98 is outside (52, 68): kept | Act1\Caves\CaveNSpec.ds1 |
|
| 5 | 24 × 24 → 9 rooms, rows then columns | 42DB84E5:07D80981 … F38BE870:3FC9280D |
first room +0x04 = 88CC16D3 |
| 9a, 4 | def 83, Files 2: Range(2) |
83D2063D:6594D62E |
idx 0x83D2063D & 1 = 1 |
| 9b | 83 is outside (52, 68): kept | Act1\Caves\CaveWPre2.ds1 (File2) |
|
| 5 | first room of its split, at (1524, 1000), 8 × 8 | 0EE3F31F:36FB3592 |
room +0x04 = step(Init(0EE3F31F)).low = 8E258975 |
| 9a, 4 | def 58, Files 2: Range(2) |
35E895EF:42FA8C7C |
idx 1, then overridden |
| 9b | 58 is inside (52, 68), first use: RangeB(2) |
80265D67:167C1E75 |
c = 1, then (1 + 1) mod 2 = 0 → idx 0, Act1\Caves\CaveSE.ds1 |
The room with +0x04 = 8E258975 is the worked example of room-tiles.md,
which takes it from creation to its active-room seed. The file the generator chose for it
(CaveWPre2.ds1) is the one whose grids the room-tile run reproduces.
Reimplementation notes
Section titled “Reimplementation notes”-
Don’t carry the create-time seed into the build. Re-initialise the level seed in
LevelInit; a model that continues fromPresetLevelCreate’s draw is off by one draw for every preset level. [C] -
Range(1)draws. A preset withFiles = 1still consumes one level draw, andFiles ≤ 0consumes none. [C] -
Overwritten draws still count. An outdoor cell’s preset index replaces the instance draw, and a maze rotation replaces it too, but the instance draw was made and stepped the level seed. [C]
-
The rotation starts one past the draw. The first use of a rotating maze def yields
(RangeB + 1) mod Files, not the drawn value. Reset the counters at everyLevelInit; keeping them across a level’s rebuilds breaks the rebuild (this was the 226-mismatch checker bug of the owner’s run). [C] -
The maze conversion walks a list that is newest first, and the maze rooms themselves are freed: a maze level’s activated rooms are all preset (type 2) rooms. [C] (
MazeLevelRooms: every Catacombs room had+0x48 = 2) -
LvlSubRolluses the room seed, not the level seed, and runs at creation, before the activation re-seed: its draws never count in k. [C]
Evidence
Section titled “Evidence”- maze.md and warps.md: the maze generator, the act links and the warp points.
- outdoor.md: the outdoor generators.
- rng/seeds: act, level and room seeds; rng: primitives.
- Tables: Levels, LvlPrest, LvlMaze, LvlSub, LvlTypes.