Install (or don’t)

You can install from GitHub to make the package available on your machine.

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

If you prefer, you can also play in your browser without having to install anything. I’ve set up a Binder instance of RStudio with {r.oguelike} preinstalled so you can just click the button below to launch it (it may take a moment to load):

This also means it’s possible to play this game from your phone, lol.

Demo

Top-tip: improve immersion by changing your console colour palette to dark mode, so it’s like you’re really inside a cave, wow.

To begin:

r.oguelike::start_game()

When you start, the console clears and the user interface is printed.

# # # # # # # # # 
# . . $ . . E . # 
# . . . . . . . # 
# . . . . a . . # 
# . . . . . @ . # 
# # # # # # # # # 
T: 25 | HP: 10 | G: 0 | A: 0
Press key to start
Input: 

At the top is a map of a dungeon room, made of floor (.) and wall (#) tiles. The room has randomly-selected dimensions from within a certain range. Within the room are randomly-placed characters and objects: the player (@), an enemy (E), and a collectible apple (a) and gold ($).

Below the dungeon room there’s:

• a status/inventory bar, which gives a numeric value for Turns remaining, Hit Points, Gold and Apples³
• a status message to provide information, usually to let the user know what has just happened
• a prompt for the user to input a key press

The game is turn-based and begins when the user chooses a direction to move the player character. There are two methods for registering a key press:

• press W, A, S or D (i.e. up, left, down or right) and hit Enter
• just press an arrow key if your console supports {keypress} (not available in RStudio), a package from Gábor Csárdi that I wrote about recently

In this demo, let’s aim first for the apple. The apple will return us 1 HP when consumed, so it’s a good idea to get it in our inventory as soon as possible. So, let’s input W and Enter (or press the up arrow if {keypress} is enabled).

# # # # # # # # # 
# . . $ . . E . # 
# . . . . . . . # 
# . . . . a @ . # 
# . . . . . . . # 
# # # # # # # # # 
T: 24 | HP: 10 | G: 0 | A: 0
Moved up
Input: 

The console will wipe the user interface will be re-printed. You’ll notice that your character has moved up one tile, the turn counter has decreased by 1 and the status message has changed to say ‘Moved up’.

Now we can move left to collect the apple.

# # # # # # # # # 
# . . $ . . E . # 
# . . . . . . . # 
# . . . . @ . . # 
# . . . . . . . # 
# # # # # # # # # 
T: 23 | HP: 10 | G: 0 | A: 1
Collected apple (+1 A)
Input: 

Again, you can see the player has progressed one tile and the turn counter decreased. You’ll notice that the inventory spot for the apple increased by 1 and the status message has changed to Collected apple (+1 A) so we know what happened.

What next? Let’s aim for the loot, signified by $ on the map. I’ll fast-forward to show you what happens after moving left twice and up twice.

# # # # # # # # # 
# . . @ . . E . # 
# . . . . . . . # 
# . . . . . . . # 
# . . . . . . . # 
# # # # # # # # # 
T: 19 | HP: 10 | G: 1 | A: 1
Found gold (+1 G)
Input: 

The player now occupies the space where the gold was and the turn counter has decreased by 4. You’ll see that the status messages has updated to Found gold (+1 G) and the gold spot in the inventory has increased by 1, but note that the amount of gold is randomly selected from a range of possible values.

There’s one obvious target left: the enemy character (E). So if we move right twice, we’ll start an encounter.

When you occupy the space of the enemy, you begin a turn-based battle. At the moment, this is actually an ‘auto-battler’: a routine is run under-the-hood where the player and enemy trade blows until one is vanquished.

Each character has attack and HP values. Of course, you can see that the player has 10 HP to start, but they also have attack strength of 2. The enemy character starts with a randomly selected HP value from within a range, and their attack strength is 1. The player attacks first, so will receive three points of damage from the enemy that has 4 HP, for example.

# # # # # # # # # 
# . . . . . @ . # 
# . . . . . . . # 
# . . . . . . . # 
# . . . . . . . # 
# # # # # # # # # 
T: 12 | HP: 7 | G: 1 | A: 1
You win! (-3 HP)
Input: 

So we know we won because the status message changed to You win! and a note of how many hit points we lost: (-3 HP). Concurrently the HP in the inventory bar has reduced by that amount.

Having lost some HP, we can add some back by consuming the apple, an action mapped to the number 1 key on your keyboard (regardless of whether you’re using {keypress} or not).

# # # # # # # # # 
# . . . . . @ . # 
# . . . . . . . # 
# . . . . . . . # 
# . . . . . . . # 
# # # # # # # # # 
T: 11 | HP: 8 | G: 1 | A: 0
Ate apple (+1 HP)
Input: 

So we get a message Ate apple and that our hit points have increased as a result: (+1 HP). Of course, this means that the apple spot in the inventory has decreased to zero. Note that the HP maxes out at 10, so eating the apple won’t raise the HP value above that.

This is the end of the demo: you’ve collected all the items and defeated the enemy. But I also added a lose condition, which occurs when you run out of turns.

# # # # # # # # # 
# . . . . . . . # 
# . . . . . . . # 
# . . . . . . . # 
# @ . . . . . . # 
# # # # # # # # # 
T: 1 | HP: 8 | G: 1 | A: 0
Moved left
Input: a
You died (max turns)! Try again!
> 

The game ends and the command prompt (>) returns.

Engine?

The technicals aren’t much to marvel at, really, but you can take a look at the code in the GitHub repo or on the website.

I called it an ‘engine’ earlier, but that was deceitful, lol.

It’s just a while loop that keeps running so long as the is_alive state is set to TRUE. So running out of turns sets the is_alive value to FALSE and the loop is broken.

The content of the loop is run after the player inputs a key press, which results in various counters being adjusted for the HP, etc. The loop concludes by printing the room with updated player locations, inventory bar and status messsage, ready for the next input.

The room itself is just a matrix. When you move the player, a small calculation is done to determine where the player character should be in the next iteration. Imagine the player is in the centre of a 3 by 3 room, i.e. they’re in position [2,2] of a matrix with x and y dimensions of 3. If they move down, that’s equivalent to adding 1 to their current position, so 5 + 1 = 6. Similarly, moving right would be equivalent to adding 3, so 5 + 3 = 8.

matrix(1:9, 3)

##      [,1] [,2] [,3]
## [1,]    1    4    7
## [2,]    2    5    8
## [3,]    3    6    9

The code is pretty rough and you can see that the logic can start to become complicated quickly, but remember it’s just a demo for now.

Obvious improvements

There’s some obvious user-facing improvements to the features that are already in place:

• interactive turn-based battles, where the user can choose what move to make (perhaps defensive moves, HP replenishment or magic)
• enemy movement, so they aren’t just stationary
• different enemy types, with differing ‘AI’ (random movement, ‘chase’ player, etc) and attack/HP stats
• traps (e.g. certain tiles are hidden traps, some collectible items are bogus)
• fog of war/vision cones (you can’t see what’s ahead until you get there, or you can only see a certain distance around you at all times)

There’s also a big-ticket item I haven’t touched: randomised or procedural dungeon generation. This is quite a big task and might end up as a blog post of its own. I encourage you to watch Herbert Wolverson’s talk at Roguelike Celebration 2020 for some ideas on this. At least at first, it could simply involve letting the player walk through doors to a few other rooms that contain randomised items.

On the back-end, I’ve so far written everything in base R; the only dependency is {keypress} to make inputs easier for consoles that support it. But there’s only so many if-else statements you can write before your brain explodes. To this end, I’m working in a branch to make use of the object-oriented approach of the {R6} package–as used in {ActionSquirrel}–to create general objects like enemies, rooms, etc, that should make it easier to handle and work with the elements of the game.