Level generation

Verified against the spelunky.ai port v0.1.10 on 28 October 2026.

This page describes a secret.

No two games are the same: each level is made when the player enters it, from rolls of the game's random number generator. The path comes first, so that the exit can be reached from the entrance; then each of its sixteen rooms is picked from its area's layouts; then a pass over every block adds the monsters, traps and treasure. A level may also be a special one, a dark level or a snake pit, with odds the game sets once for all, on the levels of the areas that can have it. The areas' own rules are on their pages: the Mines, the Jungle, the Ice Caves, the Temple and Olmec's Lair.

A level is made when its room starts with a game in progress: the object that runs the level calls the generator from its create event ^[1]. The screen between levels picks the room: the Ice Caves have a room of their own, a flooded level another, Olmec's Lair a third, and every other level shares one ^[2]. The area comes from the level's number: levels 1–4 are the Mines, 5–8 the Jungle, 9–12 the Ice Caves, 13–15 the Temple and 16 Olmec's Lair ^[3]. The Tutorial and custom levels from the level editor are laid out by hand, and get no monsters or treasure from it ^[4].

A level is four rooms by four, each 10 tiles wide and 8 high, a tile being 16 pixels ^[5]. Around them runs a border of blocks that nothing destroys; the Ice Caves' and Olmec's Lair's have no bottom, and a flooded level's is lower, to make room for its lake ^[6]. Olmec's Lair is a hall laid out by hand, with only the rooms above it made this way (Olmec's Lair).

The generator first lays a path through the grid ^{[7] [8]}:

1. It starts in a random room of the top row, which will hold the entrance.
2. From each room it rolls a move. In the two middle columns, the move is left two times in five, right two in five and down one in five; at the left or right edge, it's away from the edge two times in three and down one in three.
3. A move sideways takes the path into the next room. A move toward a room the path already has goes the other way instead if that room is free, or down if it isn't; at an edge it does nothing, and the walk rolls again (Quirks).
4. A move down marks the room it leaves as a drop and the one it enters as dropped into. A move down from the bottom row ends the path: the room it leaves holds the exit.

The path is there so that the exit can be reached, "generally no bombs required", as the code's comment says ^[9]. The rooms it doesn't take are side rooms. Each room's place on the path decides its layouts, which leave a way on along the path; a side room's needn't lead anywhere ^[10]:

That table is the Mines' room script; each area has its own, with its own layouts, and the special levels with them ^[18]. A layout has slots for chunks of 5 tiles by 3, picked at random (a platform, a mound with Spikes, an overhang), and the start and end rooms' slot for the door picks one with the door in it ^[19]. Then each tile is made: a block of the area's earth, or, one time in ten in the Mines, a stone block; some tiles are a block only half the time ^[20].

From level 2 to level 15, a level rolls for a shop with a chance of 2 in its level's number: the roll always passes on level 2, 2 times in 5 on level 5, 2 in 15 on level 15. The shop's room is a side room beside the path, picked at random from those that qualify, and a level with none gets no shop; its kind is the room script's roll ^{[21] [17]}. Once the game has had the Black Market, no level has a shop again (Quirks).

Some rolls turn rooms of the grid into something else, before or after the path is laid ^[22]. The graveyard's roll comes next, before the rooms are built, and the dark level's after ^[23]:

The Black Market can be a graveyard level as well, and the City of Gold a dark level or a sacrifice pit, as their pages say.

Four things are made once a game, each on one of a few levels, until it's made:

A game started from one of the Tunnel Man's shortcuts skips the levels before it, and with them the chances of the first ones. Reaching the Black Market and Reaching the City of Gold walk through finding and using the two doors.

Once the rooms are built, a last pass goes over every block outside the shops, in the area's own way ^[37]:

• Monsters hang under a block with open space below it (in the Mines, a Bat 1 in 60, a Spider 1 in 80) or stand on one with open space above (a Snake 1 in 60), each roll made once the ones before it fail. In the Mines, none start in the start room ^[38].
• Treasure goes on top of a block with nothing over it: a Rock 1 in 100, or a Jar 1 in 40; failing those, in a nook one block high, a Web, the Udjat Eye's chest, a Crate, a Chest, the Damsel (once a level), bones, gold or a big gem; in a tunnel, a Web, gold, bones or a big gem; on open ground, gold or bones. Nothing goes within two blocks of the entrance or the exit ^[39].
• Gold in the rock is the blocks' own: a block of the Mines' earth shows gold 29 times in 100, and one that doesn't may hold a big gem or, 1 time in 1,200 once those fail, an item ^[40].
• Traps: in the Mines, one stone block in four that has open space on one side and a block on the other becomes an Arrow Trap facing the open space, unless it's close to the entrance ^[41].

The areas' Inhabitants sections have their monsters and odds. The pass ends with a crate of flares beside the entrance of a dark level; then the player is put at the entrance, a thief or murderer finds an angry Shopkeeper at the exit, and any treasure inside a block that can't be destroyed is removed ^{[42] [43] [44]}.

Every roll comes from the game's one random number generator, which play draws from too: monsters, items and even the particles each take numbers from it, so a level depends on everything that happened before it. The game never seeds the generator; GameMaker seeds it at random when the game starts ^[45]. A test such as a and rand(1, n) == 1 draws its number even when a is false, which moves the generator on for rolls that can't come true ^{[46] [47]}. The same starting value and the same keys make the same levels again, which this wiki's replays rely on: the clip below comes from one that starts the generator at 2 ^[48].

• A path. On the first level with seed 2, the path starts in the top row's leftmost room, crosses the row to its right end and drops, crosses the second row back to the left and drops again. The player follows it: right along the top row, down at the right edge, left along the second row and down at the left ^[60].
• A move that goes the other way. On the first level with seed 1, the walk rolls a move left twice in the third row, each time toward a room it has already taken, and moves right instead ^[61].
• No room for a shop. Level 2 with seed 5 rolls its shop, but its only side rooms are on the bottom row, one not beside the path and one with the path on its left, so it gets none ^[62].
• A dark level. Level 2 with seed 2 loads dark, with the crate of flares by the entrance ^[63].

• A snake pit. A shaft of side rooms down a Mines level, with Snakes and two big rubies at its bottom ^[64].

• A flooded level. A Jungle level whose bottom row is a lake, with the exit just above the water ^[65].

• The Moai. An Ice Caves level with the Moai's room on it ^[66]. With seed 2, the Moai comes on level 9, and level 11 has a mothership ^[67].

• A sacrifice pit. A Temple level with the pit's column of rooms, a Damsel and a Golden Idol at its top ^[68].

Level generation keeps several bugs of the original's code, each a row of docs/quirks.md:

• The path walk's moves go the other way. Each else of the walk's moves belongs to the if nearest it, not to the edge check its indentation pairs it with, so a move toward a room the path already has goes the other way, or down, rather than being rolled again. The path runs on across a row more than it would otherwise ^{[47] [61]}.
• A shop faces left only from the rightmost column. A side room with the path only on its left is a shop only in the last column, so a level whose shop roll passes can still have none ^{[47] [62]}.
• No shops after the Black Market. Once the Black Market is made, the shop roll never passes again that game ^{[47] [69]}.
• No flooded level after the Black Market's door. The lake is only rolled until the market's door is taken, so the Jungle levels after it are never flooded ^[47].
• No mothership or Yeti lair before the Moai. Their rolls are the else of the Moai's, which every Ice Caves level takes until the Moai is made ^[47].
• A dark level needs the clock past 20 seconds. It's ruled out after a level finished 20 seconds or less past a whole minute, and a dark roll on the Black Market's level, which stays lit, uses up the Jungle's dark level ^[47].
• Webs eleven times as often. A misplaced bracket makes the web odds always take the branch meant for near a Giant Spider ^[47].
• Sealed in the rock. The Udjat Eye's key, the gold door and the City of Gold's Lady Xoc statue can each land where no way leads, which only bombs open ^[47].
• Blocks under the Ice Caves. A row of blocks lies under every Ice Caves level, out of reach, with treasure on it ^[47].
• Places. The Black Market can be a graveyard level that never says so (Black Markets on graveyard levels), can have two General Stores (Two General Stores), and its door's fallback can make several doors; a graveyard level can have several Ash graves (Several Ash graves); the City of Gold's stone blocks give no gold (Stone blocks without gold); and Olmec's Lair rolls a path and a shop that nothing uses ^[47].