Hacking a JavaScript text adventure game 1

Here we look at how to create a simple JavaScript adventure game for students new to JavaScript.

1. What is a text adventure game?
2. What is JavaScript?
3. Getting started
4. Explaining the code
5. What's next?

1. What is a text adventure game?

In our example we will create an adventure game in which you are presented with a series of choices. By clicking on the choice you want you will proceed to new sections of the game.  The format is similar to the awesome Fighting Fantasy series of games.  In our example we will allow options to be presented to the player only if specific tasks have been completed, or hidden from the player if a task has already been completed.  In this way we can create simple puzzles.

2. What is JavaScript?

JavaScript is the language of your web browser.  It allows web pages to be interactive.  Head over to w3schools.com for a full course on web programming.  Thankfully JavaScript is really easy to learn.

3. Getting started

You will need a copy of three files to use this example.  Download now.

The files are:
index.html (this is the code for the main page)
flags.json (this code keeps track of the various flags used in the game; more on this later)
script.json (this code keeps all of the adventure game - the options and paragraphs of text).

You will need a text editor program to use the files. I use Sublime text, but Notepad++ will work just as well.  The notepad that comes with your operating system will work, but it wont have some of the 'bells and whistles' that the others have.

4. Explaining the code

In the adventure game you will get a series of paragraphs and options. By clicking the options you will be sent to new sections of the game.  In this way we can create simple puzzles.  The flow of the game is controlled by 'flags'.  Flags start in the 'off' position and can be turned 'on' by visiting certain locations in the game. Flags are used to keep track of the events, in this example - have you found the key?

  • Run the index.html file in your web browser (it should be as simple as clicking on the icon) and you should see something similar to the following:

A simple introduction to how it all works. Here we are at location '0'.  By clicking the link we are sent to location '1' where we find the key.  When we get back to location '0' you should see that this link has been replaced by another one allowing you to exit the room.  It is rather simple, but we have just solved our first puzzle,

In this example you need to find the key under the mat before you can open the door.  Notice that once you have found the key you are no longer offered the option to 'Check under the door mat', but instead a new option of 'open the door appears'.  This works because we use a flag to let the browser 'remember' that we have found the key already.

  • Open the file script.json in your editor.  It looks like this to me:
This file contains the information about the various locations in the adventure.  Yes, the adventure game is a bit boring right now, but this is just to show you what is going on.

The file contains two locations: "In the cell" and "A key!".  For hereafter we shall call this locations 0 and 1 respectfully.  Each location has some information associated with it.  First, a location must be contained within the open and close { } curly brackets.  Second, each location is separated with a comma:  { }, { } etc.  Each location has six properties:

  • title - this will appear on screen at the top of each paragraph.
  • content - this is a paragraph of text in html. You need the <p> and </p> tags to open and close the paragraph. You can have multiple paragraphs simply by having multiple tags "<p>para 1</p><p>para 2</p>" 
  • image - this is for displaying an image with each paragraph. We'll come to how to make this work in a later post.
  • turnFlagOn - this is a list of flags that will get switched on when you read this paragraph.  For example, if the list was "[2,4,5]", then flag 2, 4 and 5 will be switched to 'on' when this paragraph is read.
  • turnFlagOff - this is the opposite of the turnFlagOn property above, but it is reserved for a later post for simplicity.
  • urlink - this is the list of options for the current paragraph.  Each option has four parameters explained below.

Looking at the very first option for location 0, we have:

"urlink": [["Check under the door mat.", 1, -1, 0], ["Open the door", 2, 0, -1]],

This means that this location has two links - "Check under the door mat" (option 0) and "Open the door" (option 1).

Looking at option 0, we have the first item in the list is the text that will be displayed on screen.

The next value is '1'.  This means that successfully clicking on this link will send you to location 1 (we are currently at location 0).

The next value is -1.  This means 'ignore'.  If it was any other value it would point to a flag that must be switched on in order for the link to be displayed.  You can look at the list of flags in the flags.json file.

The final value is 0.  This means 'don't show this link if flag 0 is on'.  This is useful if you have completed a task and so you don't need that option anymore  (there is no point looking under the mat once you have found the key).

Now look at the second link "Open the door".  The numbers mean: "go to location 2 if you successfully click the link", but don't show this option until flag 0 is on.

  • Open the flags.json file.  It looks like this to me:

The contents of the flags.json file.
Each flag is like a switch.  It can be on or off (or more correctly true or false).  The "description" is not used by the program (yet) and is there to help you remember what each flag is for.

To add more flags, use the { } notation separated by commas.

5. What's next?

Start by trying to add new locations or changing the existing ones.  In future posts we will extend the game, add some images and explain some more of the code.