Code A Parser-Based Room Escape Game, In An Hour, With Adventuron

9 min readMay 19, 2019

This article details how to create a very simple parser-driven room escape game — playable on desktop and mobile.

Behind Closed Doors, 1988 ….

John Wilson of Zenobi software created the single-location Room Escape genre in the mid-80s with his “Behind Closed Doors” series of games in which the protagonist is trapped in a lavatory.

For those that are unfamiliar, room escape games have a simple conceit.

The protagonist is usually trapped in a room for some reason and must to escape by investigating and manipulating their environment.

Typically there is a master puzzle (such as opening a door), and there are many many sub puzzles on the path to solving the master puzzle.

With only one location, there is no distracting navigation to get in the way of puzzle solving.

Room escape games can also escape the need for a deep narrative too, so they provide a way for less literary coders to create narrative-less puzzle boxes (although it should be pointed out that the original BCD games did have a narrative).

Modern games such as “The Room” series follow the same basic formula, but instead of parser based puzzle solving, the room uses mechanic/visual based puzzles.

Game Design

The game we will create here will use a simple puzzle tree simply for demonstrative processes.

The puzzle chain for this TRIVIAL tutorial game can be described as follows.

The door is locked, the key is in lock, but on the other side of the door.
To obtain the key, place some paper (obtained from the wallpaper on the wall) underneath the door, then using a pen to push the key onto the paper, then pulling the paper back.
After obtaining the key, the door can now be unlocked, and the game is won.

This puzzle chain is very common, and variants of this is present in dozens of prior games.

Puzzle Dependency Chart

Building a puzzle dependency chart can help with conceptualising the puzzle flow before even starting to code the game.

The puzzle chain can be represented visually as follows (using Vizon):

If designing a full scale room escape game, expect to see a much wider chart. This type of chart is best explained by Ron Gilbert himself.

About The Animated Gifs

This tutorial is told through animated gifs, to demonstrate how the editor helps in the process of creating the game.

The complete code is included at the bottom of the article (approx 150 lines) should you wish to copy and paste any step.

Step 0 — Log In To Adventuron Classroom

For this tutorial, we will use the “classroom” version of Adventuron (the child-focused version), however this particular tutorial is not aimed at children.

To start coding with classroom, go to https://adventuron.io and click “Enter Classroom”.

The editor itself (currently) requires a web browser and a laptop or desktop OS (Windows, OSX, Linux, Chromebook, etc.).

Step 1 — Creating A Template

Once inside the classroom editor (a desktop pc with hardware keyboard is required for the editor), then creating a template of an adventure game is easy in Adventuron. Simple, go to the editor window, and press CONTROL + SPACE (ALT+ SPACE on OSX).

Step 2 — Delete The Connection Section

The escape room only has one room, so we don’t require the connection section. We can delete this section, and delete a few headers at the same time.

Step 3 — Define The Objects

The game features 3 carryable object. We can create these by using CONTROL + SPACE inside the objects block.

Each object required an ID and a description (including an article such as “the”, or “an”, or “a”).

Step 4 — Create Some Boolean Variables

Even though this is a relatively trivial game, there is some state handling required around the door key puzzle.

We will use 3 Boolean variables to represent the state of the key and the newspaper in relation to the door.

is_key_in_keyhole, initial value “true”.
is_key_on_paper, initial value “false”.
is_paper_under_door, initial value “false”.

We use CONTROL + SPACE to create the Boolean block, then use control space again to create each Boolean variable.

Step 5 — Describe The Room

In step one, a default room description was created.

“You are in a room”

We will still use a simple room description, but not that simple.

“You are in your cell. You see a door, a bed, and bland wallpaper adorns the walls.”

We will also rename the location id to be “cell”.

Step 6 — Add handlers for examining the surroundings (examine handlers)

This game will have 4 objects that can be examined.

The bed
The wallpaper
The door
The keyhole

Here are the actions for each of the object:

Each of these actions is in response to a player command, so we enter each of these handlers in the on_command {} block of code.

Examining (or searching) the bed will reveal (and create) the pen object.

Examining the wallpaper will reveal (and create) the strip of wallpaper object.

Examining the door will reveal that there is a keyhole, and if the paper is is under the door, will describe the paper under the door too.

Examining the keyhole will reveal there is a key in the keyhole (before poking it out), and will reveal that the key is no longer in the keyhole (after poking it out). The “\n” escape code represents a linefeed.

Step 7 -Implementing Sliding Paper Under The Door

If the player types “slide wallpaper under door” or “insert wallpaper under door” or “place wallpaper under door” whilst carrying the strip of wallpaper, then destroy the strip of wallpaper object (disappears from inventory), and set the “is_paper_under_door” flag to contain a value of true.

We also implement some error handling code here.

Step 8 — Implementing the Keyhole Poking Logic

IMPORTANT: Check the source at the bottom of the article, as this block of code has been updated to allow more combinations of inputs (such as INSERT PEN IN KEYHOLE).

If the player pokes the keyhole with a pen without the paper being slid under the door, then it’s game over.

If the player pokes the keyhole with the pen with the paper slid under the door, then we set the “is_key_on_paper” boolean variable to have a true value. We also set the “is_key_in_keyhole” variable to have a false value.

In addition, we add some error handling routines.

Step 9 — Implementing Pulling The Key Under The Door

Pulling the paper when is_paper_under_door == true, will always put the wallpaper back in the player inventory, and if is_key_on_paper == true, then it will also place the key in the player inventory.

We always set “is_paper_under_door” and “is_key_on_paper” to have false values, then we wait for input before redescribing the location.

Step 10 — Unlocking The Door

If the player attempts to unlock the door or open the door without the key, they are informed that the door is locked. If they attempt to open the door with the key in their inventory, then they are told that they unlock the door and escape, then it’s the end of the game.

Step 11 — Exporting As HTML

After testing the game, it’s time to export the game as HTML. To do this, simply go to the “Menu” button at the bottom right of the editor panel in Adventuron Classroom, and select “Compile”.

Adventuron will then create a HTML file which embeds the game and the Adventuron engine (for non commercial use).

A future release is planned that will also package as PWA.

Play game Here

Trivial Room Escape : https://adventuron.itch.io/trivial-room-escape

Complete Code Listing

Medium does not currently allow syntax highlighting unfortunately, but the code listing can still be used for copy / paste purposes.

This code listing includes a “vocabulary” section, which aliases the nouns — paper and wallpaper.

start_at = celllocations {
   cell : location "You are in your cell. You see a door, a bed, and bland wallpaper adorns the walls." ;
}objects {
   wallpaper : object "a strip of wallpaper" ;
   pen       : object "a pen"                ;
   key       : object "a small key"          ;
}booleans {
   is_key_in_keyhole   : boolean "true"  ;
   is_key_on_paper     : boolean "false" ;
   is_paper_under_door : boolean "false" ;
}vocabulary {
   : noun / aliases = [wallpaper, paper]
}on_command {: match "search bed; examine bed"  {
      : if (has_not_created "pen") {
         : print "You find something" ;
         : create "pen" ;
         : press_any_key ;
         : redescribe;
      }
   }: match "examine wallpaper"  {
      : if (has_not_created "wallpaper") {
         : create "wallpaper" ;
         : print "A piece of the wallpaper falls away" ;
         : press_any_key ;
         : redescribe;
      }
      : else {
         : print "You think you should leave the rest of the wallpaper in place." ;
      }
   }: match "examine door"  {
      : print "A solid looking oak door with a keyhole." ;
      : if (is_paper_under_door) {
         : print "The wallpaper is peeking out from under the door." ;
      }
   }: match "examine keyhole"  {
      : if (is_key_in_keyhole) {
         : print "There appears to be a key in the keyhole on the other side of the door." ;
      }
      : else {
         : print "The key is no longer in the keyhole.\nYou can't see anything else of interest due to the darkness." ;
      }
   }: match "slide wallpaper;insert wallpaper;place wallpaper"  {
      : if (is_carried "wallpaper") {
         : if (noun2_is "door") {
            : if (is_paper_under_door) {
               : print "You can't slide it under the door any more." ;
            }
            : else {
               : print "You slide the wallpaper under the door." ;
               : set_true "is_paper_under_door" ;
               : destroy "wallpaper" ;
            }
         }
         : else {
            : print "Where?" ;
         }
      }
      : else {
         : print "You don't have it." ;
      }
   }: match "poke keyhole; poke key; insert pen; put pen"  {
      : if (is_key_in_keyhole) {
         : if (is_carried "pen" && (noun2_is "pen" || noun2_is "keyhole" )) {
            : set_false "is_key_in_keyhole" ;
            : if (is_paper_under_door) {
               : print "The key falls onto the paper." ;
               : set_true "is_key_on_paper" ;
            }
            : else {
               : print "The key falls onto the floor behind the door and bounces away." ;
               : print "More planning is perhaps required." ;
               : print "GAME OVER" ;
               : end_game ;
            }
         }
         : else {
            : print "Your finger is too big." ;
         }
      }
      : else {
         : print "The key has already fallen" ;
      }
   }: match "pull paper; get paper"  {
      : if (is_paper_under_door) {
         : pocket "wallpaper" ;
         : if (is_key_on_paper) {
            : print "You pull the paper back from underneath the door. You also take the key that is resting upon it." ;
            : pocket "key" ;
         }
         : else {
            : print "You pick up the wallpaper." ;
            : pocket "wallpaper" ;
         }
         : set_false "is_paper_under_door" ;
         : set_false "is_key_on_paper" ;
         : press_any_key ;
         : redescribe;
      }
   }: match "unlock door; open door"  {
      : if (is_carried "key") {
         : print "Using the small key, you unlock the door, open it, and continue onward to your next adventure." ;
         : press_any_key ;
         : print "Thank you for playing this trivial ROOM ESCAPE game." ;
         : end_game ;
      }
      : else {
         : print "The door is locked" ;
      }
   }
}

Epilogue

If you enjoyed this tutorial, be sure to clap, blog, vlog, tweet, like, share or comment on it.

If you make a room escape game, post it on itch, and share it on twitter with the hashtag #adventuronescape.