Spelunky Level Generation

Mark Brown released an excellent video called ‘How (and why) Spelunky makes its own levels’ on his Game Maker’s Toolkit YouTube channel, showcasing level generation in Spelunky.

How Spelunky Makes Levels - YouTube
Game Maker’s Toolkit – How Spelunky Makes Levels (YouTube)

You can see footage of the Yet Another Spelunky Mod in the video showing entire levels of Spelunky Classic and aiding to visualize how individual rooms within the level are generated using hand-crafted templates with random variations. Mark’s narration and very polished editing make his video the best place to start if you’re interested how Spelunky’s levels are generated, or procedural generation in general.

If you’re interested in reading more on the subject, the next step would be to look at Spelunky Generator Lessons by Darius Kazemi or reading Derek Yu’s book, “Spelunky” (paperback/eBook). Read an excerpt from the book on Gamasutra.

You can also check out some of my previous posts linked below that contain lots of screenshots of level generation in Spelunky Classic. You could also play with generating a bunch of levels in Yet Another Spelunky Mod yourself (read farther down on the mod description page for instructions on accessing the Test Chamber, where you can generate levels to your specifications).

YASM - Test Chamber Menu
Custom level generation in YASM’s Test Chamber.
Yet Another Spelunky Mod showing full level view with path to exit.
Press F9 in YASM to save a screenshot to the game folder.

Relevant Posts

Other Links



Revisiting Abandoned Mines

I ended up resuming development of the ‘Spelunky Miner’ mod mentioned in the previous post, with the intention of making it playable enough that it can be released. The gameplay follows the formula of classic mining games where you alternate between digging for valuables in the mine and returning to the surface to sell your loot, restock your supplies, and upgrade your equipment so you can dig even deeper.

Here’s a short gameplay video:

Added another video after fixing the map, showing gameplay from the start. Progression is fast and easy right now for the sake of testing – elevators will be more expensive and maybe require a certain depth to be reached before they are available in the shop.

What are the numbers on the top left?

Spelunky Miner HUD

  • The blue bar is the amount of kerosene remaining in your lamp. As your kerosene gets low, the radius of your lamp gets smaller. Upgrade (and refill) your lamp in the shop for increased light radius – which allows you to reveal the location of valuables from greater distances – and kerosene capacity, so you stay underground longer.
  • The green arrow shows your current depth in the mine and the deepest depth you have explored. When you are on the surface, your amount of money is shown instead.
  • The brown blob is your bag, showing how many slots are being used and your maximum available slots. Upgrade your bag in the shop to hold more stuff.

In its current state, the HUD is a blatant copy of the HUD from Miner Dig Deep, the XBOX Live game that this mod is based on.

On the top right is the total amount of time played in the current game. This (and the name of the mine) won’t likely be visible on the HUD later on, but it’s shown among other stats of your saved game when you are in the Load menu.

Abandoned Caves

I’d like to write a series of posts focusing on Spelunky Classic mods that I’ve abandoned or left unfinished. As a preview, here’s some screenshots of a few of them:

This ‘Miner’ mod never had a proper name. You dig as deep as you can for ore, cashing it in and buying upgrades on the surface. In the tradition of games like Motherload (Flash) and Miner Dig Deep (Xbox Live).
The ‘Spelunky Challenge’ mod was the collaborative successor of Seed of Spelunky that added daily challenges and more. You could race against yourself or others to beat your time or score. Previous runs were recorded and the ghost images played back for you to race against.
The ‘Gardevoir’ mod. This was a collaboration (I don’t know anything about Pokemon). A spin-off of YASM where the player could drift through the air briefly and had a shield ability that would regenerate over time.
The map menu from a mod that was just called ‘Jetpack’. It was meant to be something like the game ‘Air Fortress’ (NES) but taking place in caves instead of space stations. Playing with cave generation methods was fun.
An early build of Caveman Convoy, a Lemmings clone. The yellow brick steps didn’t suit the blocky game world and were replaced with ladders and horizontal platforms instead of any diagonal digging/building abilities like the original Lemmings game.
The intro/splash screen of a mod that would let you edit all the game defaults using external text configuration files that would get loaded when the game starts. The plan was to allow for custom room templates, editing starting equipment and stats, enemy properties and spawn frequency, etc. This would allow people without Game Maker to customize the game difficulty or make simple mods. This never got off the ground enough to be playable but I guess I had fun making this stupid meme image.

Yet Another Spelunky Mod Update 1.8.1

Yet Another Spelunky Mod 1.8.1

This update includes bug fixes and new features. The YASM configuration tool has also been updated, so overwrite the old one, then run it to enable the new options. If this is your first time trying YASM, you’ll just need the ‘sound’ folder included with the original version of Spelunky Classic.

Download Yet Another Spelunky Mod 1.8.1.

  • Option for player to be able to change between walk/run speed in mid-air without touching the ground first (like Spelunky HD).
  • Option for improved water movement. Press down to sink faster, press up to sink slower.
  • When stunned enemies are about to regain consciousness, the star above their head will spin slightly faster.
  • Prevented melee weapons from nudging items that were intended to be stuck/hidden inside solid walls.
  • Made it easier for player to jump up into 1 block wide gaps.
  • Wall graphics will update when nearby walls have been destroyed to show detailed top and bottom edges instead of looking flat.
  • Destroying the stone pedestal holding a gold idol will now trigger the trap.
  • Prevented loss of bomb bag and rope pile held items (after pulling them out of inventory) when another item was pulled from inventory while they were still being held.
  • Improved explosion collisions. If there is a wall between an explosion and a damsel, the damsel is likely to survive the blast. Also, a cluster bombs will trigger each other faster instead of causing an delayed series of explosions that rises into the air.
  • Read the full release notes.
  • Main page and overview of the mod.
Two new options, found of page 3.
Two new options, found of page 3 of YASM config.

Several changes in this update were inspired by playing the two Spelunky Classic mods below. Play them yourself!

  • Spelunky SD by YellowAfterlife adds online multiplayer and chat to the game, along with many fixes.
  • Spelunky Natural by Urza focuses on the Damsel playable character, giving her special powers. With all the other fixes, improvements and a powerful level editor, it’s your best choice if you’re interested in making custom levels.

Yet Another Spelunky Mod 1.8 Released

Screens from Bizarre Mode (Classic Mode is still available!)

Get it here.

New in 1.8:

  • Test chamber has option to display solution path to exit and level generation layout (as seen in previous posts, here and here).
  • In-game help menu (press F1) for controls, inventory system, and selling to shops.
  • Bizarre Mode now has a unique ending (completing the game in Bizarre Mode unlocks Bizarre Mode Plus).
  • Enemy and loot balancing in bizarre mode.
  • Support for sprite mods.
  • Many more small improvements and fixes.

Rooms and Obstacles

Darius Kazemi recently demonstrated and explained in detail how levels are generated in Spelunky:

spelunkylessonsI’ve added similar visual aids as an option in the level generation test room for the upcoming update of Yet Another Spelunky Mod. The solution path and room layout for all four areas will be visible in playable levels from either the default view or zoomed out so that the whole level is visible.



The 5×3 obstacle templates that further randomize individual rooms are outlined in blue (air), green (ground), and red (start/exit).

The level generation test room can be accessed (in YASM 1.7+) by bringing the torch on the title screen to the background carving with the glowing eyes above the ‘K’:


I haven’t added tile labels and obstacle outlines to the jungle, ice, and temple levels yet, but I have the solution path displaying correctly in the lake levels and ice caves now.


The solution path for ice cave levels (aside from Yeti caves) don’t usually apply due to the sparse layout of individual rooms. Ice caves with alien ships ignore the solution path anyway, as there is always a route around them.


The Path Ahead

I’ve added some visuals to one of my existing Spelunky mods to compliment Darius Kazemi’s latest essays on how level generation works in Spelunky. Be sure to read the first essay, “Generating the Solution Path” to follow what’s happening in the images below.

Spelunky Solution Path 01 Mines

A quick recap of the room types that are part of the solution path:

  • Room type 1 has exits on each side.
  • Room type 2 has exits on the sides and bottom. If another room type 2 is directly above, it has an exit at the top.
  • Room type 3 has exits on the sides and top.

Spelunky Solution Path 02 Jungle

Also note that while rooms that aren’t part of the solution path may create alternative routes by chance, the solution path is intended to allow the player to reach the exit without the need of bombs or ropes.

Spelunky Solution Path 03 Temple

More images in the next post!

Spelunky Solution Path 04 City of Gold

Here’s a video of the previous version of the mod. All it does is change the scale of the game to allow the whole level to be in view, while generating a new level every 15 seconds. The idea was to create a series of videos or animated GIFs to show off the variety of possible levels. Watch in full-screen HD to avoid blurry pixels.