Install/launch

You can install the (currently work-in-progress) {r.oguelike} package from GitHub, via {remotes}.

# install.packages("remotes")  # if not already installed
install_github("matt-dray/r.oguelike")

You can also launch RStudio in the browser with {r.oguelike} preinstalled, thanks to Binder³ (may take a couple of minutes to load):

Prepare

Before we begin, note that we can talk about generative ‘dungeons’ in the context of connected rooms, like in The Binding of Isaac, or more freeform structures, like world maps in Dwarf Fortress. We’re going for the latter, which amounts to interconnected caverns.

The function we’ll be using is called generate_dungeon(), which prints to the console a cavern that differs each time you run it.⁴ You can alter the output using the arguments:

• iterations is the number of times to ‘grow’ the caverns
• n_row and n_col give the map dimensions
• n_rooms is the number of rooms to spawn
• is_snake for a cavern that is continuous from left to right and wiggly
• is_organic for a more freeform vs ‘square’ look to the caverns
• colour to print the output in colour

You can always run set.seed() before generate_dungeon() to create the same dungeon every time you run the function with the same parameters.

Demo

So here’s a smallish dungeon with 3 growth iterations for 4 starting rooms, on a map with tile dimensions of 20 rows by 30 columns.

dungeon <- r.oguelike::generate_dungeon(3, 20, 30, 4)

Here’s a screenshot of the output so you can see it in colour.

| - - - - - - - - - - - - - - - - - - - - - - - - - - - - | 
| # # # # # # . # # # # # # # # # # # # # # # # # # # # # | 
| # # . # . . . . # # # # # . # # # # # # # # # # # # # # | 
| # . . . . # . . # # # . . . . # # # # # # # # # # # # # | 
| # . . . . . . . . . . . . . . . # # # # # # # # # # # # | 
| . . . # . . # . . # # . . . . . # # # # # # # # # # # # | 
| . . . . # # # . # # # # # . . # # # # # # # # # # # # # | 
| . . # # # # # # # # # # # . # # # # # # # # # # # # # # | 
| . . . . # # # # # # # # . . . # # # # # # # # # # # # # | 
| . . . . # # # # # # # # # . . # # # # # # # # # # # # # | 
| . . . # # # # # # # . # . . . # # # # # # # # # # # # # | 
| . . . # # # # # # . . . . . . . # # # # # # # # # # # # | 
| . . . # # . . # . . # . . . . . . . . . # . . . # # # # | 
| . . . . . . . . . . . . . . . . . . . . . . . . # # # # | 
| . . # # . . . # . # . . . # . . . # # . . # . . # # # # | 
| # # # # . . . # . # # # # # . # . # # # # . . . # # # # | 
| # # # # # # # # # # # # # # # # # # # # . . . . # # # # | 
| # # # # # # # # # # # # # # # # # # # # . . . # # # # # | 
| # # # # # # # # # # # # # # # # # # # # # # . # # # # # | 
| - - - - - - - - - - - - - - - - - - - - - - - - - - - - | 

So, in this example you can see we have a little cavern with some interconnected areas and a dead-end in the lower right. The tiles represent:

• cavern-floor tiles (black periods), which is where the character can traverse
• cave wall tiles (red hashmarks, which can’t be passed through)
• a boundary around the edge (yellow hyphens and pipe symbols)

Note that the actual output from the function—a matrix that represents the dungeon tiles—is returned invisibly.

# Preview first 10 rows and columns
dungeon[1:10, 1:10]

[,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10]
[1,] "|"  "-"  "-"  "-"  "-"  "-"  "-"  "-"  "-"  "-"  
[2,] "|"  "#"  "#"  "#"  "#"  "#"  "#"  "."  "#"  "#"  
[3,] "|"  "#"  "#"  "."  "#"  "."  "."  "."  "."  "#"  
[4,] "|"  "#"  "."  "."  "."  "."  "#"  "."  "."  "#"  
[5,] "|"  "#"  "."  "."  "."  "."  "."  "."  "."  "."  
[6,] "|"  "."  "."  "."  "#"  "."  "."  "#"  "."  "."  
[7,] "|"  "."  "."  "."  "."  "#"  "#"  "#"  "."  "#"  
[8,] "|"  "."  "."  "#"  "#"  "#"  "#"  "#"  "#"  "#"  
[9,] "|"  "."  "."  "."  "."  "#"  "#"  "#"  "#"  "#"  
[10,] "|"  "."  "."  "."  "."  "#"  "#"  "#"  "#"  "#"  

More examples

I think this process works best with a larger map grid (i.e. higher n_row and n_col values), more randomly-selected room start-points (higher n_rooms) and more growth steps (higher iterations).

Here’s a larger maze-like dungeon:

This one came out more like a doughnut, with a central ‘pillar’ of rock-wall tiles:

And this one is the result of using is_snake = TRUE, which creates a single, long snaking cavern:

Here’s what happens if we set is_organic = FALSE and is_snake = TRUE. You get much obvious ‘rooms’ connected by small corridors:

And if we set is_organic = FALSE and is_snake = FALSE we get something interconnected, but looks more ‘artificial’ or manmade with its mostly square walls:

You can see how the shape of these dungeons can be used as part of the storytelling. Is the player in a big cavern, hollowed out long ago by natural processes? Or perhaps in an underground city, chiselled-out by dwarves?

Functions

These steps are handled in the generate_dungeon() function by a few sub-functions, which looks a bit like this:

m <- .create_dungeon(n_row, n_col, n_rooms)

m <- .connect_dungeon(m, is_snake)

i <- 0

while (i < iterations) {
  m <- .grow_dungeon(m)
  i <- i + 1
}

.draw_dungeon(m, colour)

Not much right? But what’s actually happening?

1. First, .create_dungeon():
   • prepares a matrix with dimensions n_row and n_col
   • fills the matrix with tiles that represent non-traversable rocky cave walls (#)
   • selects randomly an n_rooms number of non-edge tiles in that map and replaces them with traversable cavern-floor tiles (.)
2. Then .connect_dungeon() (this function is run now if is_organic = TRUE, otherwise after .grow_dungeon() in the next step):
   • connects rooms with straight, right-angled corridors made of floor tiles (connected from lowest to highest if is_snake = TRUE, otherwise randomly)
3. Now the iterative bit, .grow_dungeon(), which happens in a while-loop whose iterations are determined, which:
   • spawns randomly with sample() a new cavern-floor tile to the north, south, east or west or current floor tiles
   • performs one round of spawning for the number of iterations provided
4. Finally, .draw_dungeon():
   • prints to the console, using cat(), each line of the matrix in turn
   • colours the output with the {crayon} package, if requested

And we can look at the output at each step to see what’s going on:

So, the map started with four randomly-selected floor tiles; these were joined with straight, right-angled corridors; then three iterations expanded out the floor space from the existing floor tiles.

Sampling

What does it mean to ‘expand out the floor space’? Let’s focus on the little bit of the .grow_dungeon() function that actually does this.

Here’s a tiny example matrix of wall tiles with a floor tile in the middle:

m <- matrix("#", 3, 3)  # wall tiles
m[2, 2] <- "."  # floor tiles
m

##      [,1] [,2] [,3]
## [1,] "#"  "#"  "#" 
## [2,] "#"  "."  "#" 
## [3,] "#"  "#"  "#"

Now we find the adjacent tiles and sample a random number of them to also become floor tiles.

start_tile <- which(m == ".")

adjacent_tiles <- c(
  start_tile - 1,        # north
  start_tile + 1,        # south
  start_tile - ncol(m),  # east 
  start_tile + ncol(m)   # west 
)

change_to_floor <- sample(
  adjacent_tiles,
  sample(1:length(adjacent_tiles), 1)
)

m[change_to_floor] <- "."

m

##      [,1] [,2] [,3]
## [1,] "#"  "#"  "#" 
## [2,] "."  "."  "#" 
## [3,] "#"  "."  "#"

So one, two, three, or all of the adjacent tiles could be turned to a floor tile.

This is then repeated for the number of iterations provided by the user.