Tutorial A - The Cave of Magic

Note	Tutorial A will take between 30 and 60 minutes.

1. Introduction

In this tutorial we will create a simple text adventure game, with graphics, using Adventuron, then compile the game to a HTML file, ready to be hosted on a server of your choice.

Compiling to 8-bit platforms is also demonstrated (at the end).

If you have any problems with the documentation, or need help, don’t hesitate to use the Adventuron Discord Server.

2. The Cave of Magic

In THE CAVE OF MAGIC, the player is invited to enter the cave of magic so as to discover the treasure within.

A troll is blocking the path, and the player must solve two small puzzles in order to be able to enter the cave.

3. Pre-Requisite Knowledge

The knowledge of how to actually play text adventures has largely been lost for people under the age of 35.

As it would be extremely difficult to make a game without knowing the genre first, it is HIGHLY recommended to invest 5 minutes and play The Cave of Magic DX before proceeding.

Playing the game serves two purposes:

To learn how to play text adventure games.
To learn the design and layout of the game.

4. The Design

It is not always necessary to plan your game ahead of time but for the purposes of this tutorial we will note the functionality we want to code inside this game.

4.1. Goal

The game will be won when the player finds the treasure in the cave of magic.

4.2. Map

The game consists of four locations - the lakeside, the forest, outside the cave, and inside the cave.
To the north of the lakeside is the forest. The forest location description notes that there are tall trees standing overhead.
To the north of the forest is the entrance to the cave.
To the north of the entrance to the cave is the inside of the cave.

4.3. Design

In this section, I will outline how the game should react to the player and what puzzles are in the game.

4.3.1. At The Lakeside

com lakeside

(art by Ricardo Oyón)

The player starts in the lakeside location.

4.3.2. In The Forest

com forest

(art by Ricardo Oyón)

When examining the “trees” in the forest location, the player is informed that the trees are apple trees.

Note	This invites the player to experiment with commands such as “pick apple” or “get apple”.

If the player types “get apple” or “pick apple” in the forest location, and the game has not yet created an apple in the game, then the player is given an apple.
If the player looks at (or examines) the apple, the game will inform the player that the apple is an enchanted apple.

4.3.3. Outside The Cave

(art by Ricardo Oyón)

We will place a troll outside the cave.
If the troll is outside the cave then the player will not be permitted to enter the cave.
When standing next to the troll, the troll will tell the player that it will not let the player enter the cave.

Note	This lets the player know that the troll is the reason they cannot enter the cave, and that the likely solution involves the troll.

When examining, looking at, or speaking to the troll, the troll tells you that it is hungry.

Note	This information should guide the player to a possible idea for removing the troll as an obstacle.

If the player gives the apple to the troll then the troll will be replaced by a sleeping troll (as the apple was enchanted).
With the troll asleep, the barrier stopping the player from entering the cave is deactivated.

4.3.4. Inside The Cave

(art by Ricardo Oyón)

When the player starts the game the game will inform the player that the player must enter the cave of magic, to reach the treasure inside.

Note	It is important to let players know what their goal is so that they have their bearings in the game. Their first task will be to see what is standing in the way of their goal, which should lead them to the chain of clues.

We will place the treasure initially inside the cave.
If the player enters the cave, then print a message telling the player they have “won” the game, and end the game.

5. Loading Adventuron

Warning

Adventuron’s editor requires a PC or Mac with mouse and keyboard attached (not a tablet or smartphone).

Navigate to https://adventuron.io/classroom (using a non-mobile web browser).
If you want to get rid of the left panel (Tutorial B is built-in), click the MENU button at the bottom of the middle panel, and select "Display Side Documentation". Adventuron will reload with only two panels.

6. First Code

Note	A YouTube Video of this tutorial is available, but it is highly recommended to follow the course before viewing the video.

To create a template, simply click inside an empty editor window, and hold the CONTROL button on your keyboard, and tap the SPACEBAR.
You should now see a template as shown above.

Warning

If you don’t see the template as shown above, then try ALT and SPACE together (you may have problems if using the OPERA web browser).

Press the PLAY icon to test the game.

7. The Lakeside

The first location we will create in the game is the lakeside.

Change the part of the text that says my_location (inside the locations {} section), and change it to lakeside.
Now change the text that says “You are in a room.” To say “You are by the side of a beautiful lake”.
Now change text that says “start_at = my_location” to say “start_at = lakeside”.
Now hit the PLAY button at the top.

Code so far:

######################################
#  Adventuron                        #
######################################

start_at                 = lakeside

######################################
#  Locations                         #
######################################

locations {

   lakeside : location "You are by the side of a beautiful lake." ;

}

######################################
#  Connections                       #
######################################

connections {

   from, direction, to = [

   ]

}

######################################
#  Objects                           #
######################################

objects {

}

8. More Locations

Now we will add a few more locations.

Location Id	Description
lakeside	You are by the side of a beautiful lake.
forest	You are on the forest path.\nTall trees tower over you on both sides.
outside_cave	You are standing outside the cave of magic.
inside_cave	You are inside the cave of magic.

Location Id

Description

lakeside

You are by the side of a beautiful lake.

forest

You are on the forest path.\nTall trees tower over you on both sides.

outside_cave

You are standing outside the cave of magic.

inside_cave

You are inside the cave of magic.

Note	In the forest location, \n is a special piece of text we can use to tell Adventuron to insert a paragraph break. Think of it as if you are typing on screen, and \n represents pressing the ENTER key.

(For each location you want to add)

Go to a blank line (inside the locations{} section), and press CONTROL + SPACE (for the first added location, the line underneath lakeside is the correct line).
When the new location template line appears, the first thing you should do is type the ID of the location you are adding (see table at the top of this section). Typing immediately will overwrite the existing id.
If you didn’t use the cursor keys, when editing the ID previously, you can press the TAB button on your keyboard to select the description of the new location. Or you can delete the existing location text manually.
Next, type the description of the next location you are entering between the "" characters.
If you have more locations to create, go back to step 1 for each additional location as per the table at the top of this section.
Press the PLAY icon to test the game.

Your locations {} section should look like this:

locations {
   lakeside     : location "You are by the side of a beautiful lake." ;
   forest       : location "You are on the forest path.\nTall trees tower over you on both sides." ;
   outside_cave : location "You are standing outside the cave of magic." ;
   inside_cave  : location "You are inside the cave of magic." ;
}

9. Connections

Next, we create connections between our locations.

This is a quote from the design section of this tutorial.

"the forest is north of the lakeside, outside the cave is north of the forest, inside the cave is north of the outside of the cave."

Now let’s put this information into Adventuron.

From	Direction	To
lakeside	north	forest
forest	north	outside_cave
outside_cave	north	inside_cave

From

Direction

lakeside

north

forest

north

outside_cave

north

inside_cave

First move cursor to the empty line below the (from, direction to = [ line).
(Do not use mouse) Press CONTROL + SPACE (this will give you a list of locations), select "lakeside" with your cursor keys then press ENTER.
(Do not use mouse) You should now see that the current line reads "lakeside, " with your cursor flashing at the end of the line, press CONTROL + SPACE again to see a list of directions, select "north" by using cursor keys, then press ENTER.
(Do not use mouse) You should now see that the current line reads "lakeside, north, " with your cursor flashing at the end of the line. Press CONTROL + SPACE again to see a list of locations, select "forest" by using cursor keys, then press ENTER.
This is one complete connection, you can press the PLAY icon to try this out right now. If you see an error at the top, please check that you didn’t type something wrong, or copy and paste from the code block at the bottom of his section. Assuming the first connection was keyed in correctly, then repeat steps 1 - 4 for the remaining two connections lines (using the table above as reference).
Press the PLAY icon to test the game.

Your connections {} section should look like this:

connections {

   from, direction, to = [
      lakeside,     north,        forest,
      forest,       north,        outside_cave,
      outside_cave, north_oneway, inside_cave,
   ]
}

10. Objects

Note	See animated gif for demonstration of steps here.

Next, we create objects in the game. We move our cursor inside the objects {} section.

As per the design, the four objects that we will create will be as follows:

id	type	description	at
troll	scenery	an enormous troll (guarding cave to the north)	outside_cave
treasure	scenery	a pile of treasure	inside_cave
apple	object	an apple	-
sleeping_troll	scenery	an enormous troll (sleeping)	-

type

description

troll

scenery

an enormous troll (guarding cave to the north)

outside_cave

treasure

scenery

a pile of treasure

inside_cave

apple

object

an apple

sleeping_troll

scenery

an enormous troll (sleeping)

Scenery objects are objects that cannot be picked up. Regular objects can be picked up and dropped.

Objects with an "at" value will start somewhere when the game is started. Objects without an at are outside the game world when the game starts (they don’t exist - but can be created later).

Move the cursor to a blank line in the objects {} section.
We press CONTROL + SPACE on a blank line to create objects. When a new line is created we can immediately type the "id" (or identifier) of the object. The id of the object is how we can refer to the object in the rest of the code.
After typing the id, then you can press TAB to select the description of the object, then start typing the object description.
If an object has an "at" value, then move the cursor just before the ";" character, then press CONTROL + SPACE, and select "at" then when between the "" characters, press CONTROL + SPACE again to see a list of locations where to place the object. Select the appropriate location, then press enter.
Press the down arrow to move to a new line then re-do steps 1 to 4 for each object you want to add.
Now, press the PLAY icon to test the game.

Your objects{} section should look like this:

objects {
   troll          : scenery "an enormous troll (guarding cave to north)" at = "outside_cave" ;
   sleeping_troll : scenery "an enormous troll (sleeping)" ;
   apple          : object  "an apple" ;
   treasure       : object  "a pile of treasure" at = "inside_cave" ;
}

11. Barriers

In this section we want the game to refuse entry to the cave of magic (inside_cave) whilst the troll exists in the game. Adventuron has a simple method of blocking access to a location, and that is by use of the barriers {} section.

We press CONTROL + SPACE outside of one of the existing sections, and select "barriers".
Inside the barriers section, press CONTROL + SPACE to create a barrier. Type "cave" where the cursor appears (so that the identifier reads block_cave").
Next, press TAB to move to the right side of "location =" then press CONTROL + SPACE and select "inside_cave".
Next, press TAB, to move the cursor to the right side of the "message =" line, and type the message "THE TROLL IS GUARDING THE CAVE.".
Now we need to make an extra line which isn’t immediately presented to us. currently we have defined a permanent block, in that it is always blocking. To make the block dependent on something else, we need to create a condition (or a clause).
Move the cursor to a blank line below the "message = THE TROLL IS GUARDING THE CAVE." line, and on that line, press CONTROL + SPACE, and select "block_when_exists", then press ENTER. This will create a line, and move the cursor to the right side of "block_when_exists = ".
Now press CONTROL + SPACE again, and select "troll".
Now, press the PLAY icon to test the game.

Note	The block we just created will only be blocking as long as the troll exists in the game. Hypothetically, if we were to remove the troll from the game, the game would stop blocking access to inside the game.

Your barriers {} section should look like this:

barriers {
   block_cave : block {
      location               = inside_cave
      message                = THE TROLL IS GUARDING THE CAVE.
      block_when_exists      = troll
   }
}

12. Startup

In this section we will code a routine that will print the goal of the game ("You must find the treasure in the cave of magic.") when the game starts.

We press CONTROL + SPACE outside of one of the existing sections, and select "on_startup" to create the "on_startup {}" section.
Press CONTROL + SPACE inside the on_startup {} section and select the PRINT command, then type "You must find the treasure in the cave of magic.".

Press the PLAY icon to test the game.

Note

You should notices that even though we told adventuron to print a message, that you can’t actually see the message. This is because the message is printed, then immediately after running the on_startup {} block, the screen is cleared and the first location is displayed. We need to wait for the player to click, touch, or press a key.

On the (empty) line directly below the previously coded print statement, press CONTROL + SPACE on the next line to add a "press_any_key" command (which will force adventuron to wait for a keypress or mouse click or touch event).

Press the PLAY icon to test the game.

Your on_startup {} section should look like this:

on_startup {
   : print "You must find the treasure in the cave of magic.";
   : press_any_key ;
}

13. A Troll’s Warning

In this section we will code a routine that prints a message when the troll is in the same location as the player (as per the design).

We press CONTROL + SPACE outside of one of the existing sections, and select "on_describe" to create the "on_describe {}" section.
Inside the "on_describe {}" section, press CONTROL + SPACE, and select "if" to create a conditional block.
With the cursor between the parenthesis "()", press CONTROL + SPACE and select "is_present". The cursor should now be placed between "" characters on the same line. Press CONTROL + SPACE again, and then select "troll"

Note	This will tell adventuron to only run the code inside the if statement only if the troll is in the same location as the player character.

Next place the cursor on the empty line underneath the line with the "if" statement, and press CONTROL + SPACE, and select "print" command, then type "The troll says, \"THE CAVE IS MINE, GO AWAY.\" " (between the quotes).

Warning

If typing the " character then you need to prefix it with a backslash character, e.g. \". If you don’t do this, then Adventuron will interpret the double quote as ending the text you want to print.

Press the PLAY icon to test the game.

Your on_describe {} section should look like this:

on_describe {

   : if (is_present "troll") {
      : print "The troll says, \"THE CAVE IS MINE, GO AWAY\"." ;
   }

}

14. Winning

Next we will tell Adventuron that the game is won when the player enters the cave of magic.

Beneath the previous 'if' statement in the on_describe section, press CONTROL + SPACE, and select "if" to create a conditional block.
With the cursor between the parenthesis "()", press CONTROL + SPACE and select "is_at". The cursor should now be placed between "" characters on the same line. Press CONTROL + SPACE again, and then select "inside_cave".
Next place the cursor on the empty line underneath the line with the "if" statement, and press CONTROL + SPACE, and select "print" command, then type "CONGRATULATION ! YOU WON THE GAME ! YOUR RANKING IS : JUNIOR ADVENTURER !" (between the quotes).
On the next line, press CONTROL + SPACE, and select "win_game". This tells adventuron to end the game after a press_any_key event, which then tells the game to restart.
Press the PLAY icon to test the game.

Your on_describe {} section should look like this (including the entry we made in the last section):

on_describe {

   : if (is_present "troll") {
      : print "The troll says, \"THE CAVE IS MINE, GO AWAY\"." ;
   }

   : if (is_at "inside_cave" ) {
      : print "CONGRATULATIONS !" ;
      : print "YOU WON THE GAME !" ;
      : print "YOUR RANKING IS : JUNIOR ADVENTURER !" ;
      : press_any_key ;
      : clear_screen;
      : win_game ;
   }
}

15. Trees Bon

In this section we will display a message if the player looks at or examines the trees in the forest. This examine message will let the player know that they might be able to pick (or get) an apple.

Tip	Clues (also known as examine messages) can be the difference between an enjoyable game and a frustrating game.

First, we press CONTROL + SPACE outside of one of the existing sections, and select "on_command" to create the "on_command {}" section.
Inside the on_command section, press CONTROL + SPACE, and select "match" to create a input matching block.
Between the double quotes, type "examine trees;examine tree"

Note	The ";" character allows multiple user-entered verb nouns patterns to match. There is no limit to the amount of verbs and nouns that can be matched using this method.

On the next line, press CONTROL + SPACE, and select "if" to create a conditional block.
With the cursor between the parenthesis "()", press CONTROL + SPACE and select "is_at". The cursor should now be placed between "" characters on the same line. Press CONTROL + SPACE again, and then select "forest".
This tells adventuron to only execute the inner code if the player types "examine tree" or "examine trees" and if the player is in the forest location.
On the blank line inside the inner if statement, press control and space, and press CONTROL + SPACE, and then select "print". Type the message "Apple trees". This will let the player know that they should try picking (or getting) and apple.

Note	Adventuron automatically understands "examine" as "look" (and the other way around) when used with a second word (a noun).

Press the PLAY icon to test the game.

Your on_command {} section should look like this:

on_command {

   : match "examine trees; examine tree"  {
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

}

16. The Hungry Troll

Next we plant a clue that tells the player that the troll is hungry. This clue is important so that the player know what kind of solution might work with the troll, and so they feel that the game doesn’t require mind reading.

Inside the on_command section, press CONTROL + SPACE, and select "match" to create a input matching block.
Between the double quotes, type "examine troll;talk troll"
On the next line, press CONTROL + SPACE, and select "if" to create a conditional block.
With the cursor between the parenthesis "()", press CONTROL + SPACE and select "is_present". The cursor should now be placed between "" characters on the same line. Press CONTROL + SPACE again, and then select "troll".
This tells adventuron to only execute the inner code if the player types ("examine troll" or "talk troll") AND if the player is in the same location as the troll.
On the blank line inside the inner if statement, press control and space, and press CONTROL + SPACE, and then select "print". Type the message "\"I’M SO HUNGRY\", says the enormous troll.".

Press the PLAY icon to test the game.

Tip	Examine messages hint to the player about how to solve a particular problem. The player now knows that the troll puzzle probably involves food and therefore will stop assuming that they can solve the puzzle with verbs and nouns without the addition of some kind of food being carried.

Your on_command {} section should look like this (including the entry we made previously):

on_command {

   : match "examine trees; examine tree"  {
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

   : match "examine troll;talk troll"  {
      : if (is_present "troll") {
         : clear_screen;
         : print "\"I'M SO HUNGRY\", says the enormous TROLL in the deepest possible voice." ;
         : press_any_key ;
         : redescribe;
      }
   }

}

17. Creating The Apple

We will now create code that will put an apple in the pocket of the player if they type "GET APPLE or "PICK APPLE" in the forest, and if the game has not created an apple before.

Move your cursor down to an empty line at the bottom of (but inside) the on_command {} section.
Press CONTROL + SPACE, and select "match" to create a input matching block and between the double quotes, type "pick apple;get apple"
On the next line, press CONTROL + SPACE, and select "if" to create a conditional block.
With the cursor between the parenthesis "()", press CONTROL + SPACE and select "is_at". The cursor should now be placed between "" characters on the same line. Press CONTROL + SPACE again, and then select "forest".
Now, we will move the cursor one to the right (press right arrow key on keyboard). The cursor should be past the " character but before the ")" character.
Now type " && " (without the quotes). This means AND.
Press CONTROL + SPACE again and select "has_not_created". The cursor should now be placed between "" characters again. Press CONTROL + SPACE again, and then select "apple".

Note	The logic we created here tells adventuron to only execute code inside the 'if' statement ONLY IF the player types ("get apple" OR "pick apple") AND if the player is in the forest AND if the apple has not previously been created before.

Tip	If you want to check for multiple things at the same time, then type && between those things. In this example, we have two things we are testing for at the same time, but there is no limit to the number of things you might want to test.

On the blank line inside the inner if statement, press control and space, and press CONTROL + SPACE, and then select "print".
Type the message "You take an APPLE from one of the trees.".

Tip

When you perform an action it is usual to report to the player what the player character just did. Just performing the action will reward the player with no response for their input, making the player confused what happened. The player relies on you to be a good narrator so you should give an update when changing the state of the game, or rejecting a command for some reason.

On the next line, press CONTROL + SPACE, and select "pocket" and in the quotes, press CONTROL + SPACE again, and select "apple".

NOTE : The pocket command tells adventuron to put the apple (which previously did not exist anywhere in the game) inside the player’s pocket.

Press the PLAY icon to test the game.

Your on_command {} section should look like this (including the entries we made previously):

on_command {

   : match "examine trees; examine tree"  {
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

   : match "examine troll;talk troll"  {
      : if (is_present "troll") {
         : clear_screen;
         : print "\"I'M SO HUNGRY\", says the enormous TROLL in the deepest possible voice." ;
         : press_any_key ;
         : redescribe;
      }
   }

   : match "pick apple;get apple"  {
      : if (is_at "forest" && has_not_created "apple") {
        : print "You take an APPLE from one of the trees." ;
        : pocket "apple";
      }
   }

}

18. Troll Swap

We will now write logic in which if the player types "GIVE APPLE" when in the same location as the troll, and when carrying the apple, that the game will swap the troll for the sleeping troll, and destroy the apple (as the troll ate it).

Note	Swapping the (existing) troll for the (non-existing) sleeping troll will mean that the block we made earlier, that was conditional on the troll 'existing', will become deactivated, and the player will be able to move into the cave of magic, and the game win code will be triggered.

Move your cursor down to an empty line at the bottom of (but inside) the on_command {} section.
Press CONTROL + SPACE, and select "match" to create a input matching block and between the double quotes, type "give apple".
On the next line, press CONTROL + SPACE, and select "if" to create a conditional block.
With the cursor between the parenthesis "()", press CONTROL + SPACE and select "is_present". The cursor should now be placed between "" characters on the same line. Press CONTROL + SPACE again, and then select "troll".
Now, we will move the cursor one to the right (press right arrow key on keyboard). The cursor should be past the " character but before the ")" character.
Now type " && " (without the quotes). This means AND.
Press CONTROL + SPACE again and select "is_carried". The cursor should now be placed between "" characters again. Press CONTROL + SPACE again, and then select "apple".

Note	The logic we created here tells adventuron to only execute code inside the 'if' statement ONLY IF the player types "give apple" AND if the player is in the same location as the troll AND if the player is carrying the apple.

On the blank line inside the inner if statement, press control and space, and press CONTROL + SPACE, and then select "print".
Type the message "The troll grabs the apple from you hungrily. Unfortunately (for the troll), the apple is an ENCHANTED APPLE, and sends the troll directly to sleep.".
On the next line, press CONTROL + SPACE, and select "destroy" and in the quotes, press CONTROL + SPACE again, and select "apple".
On the next line, press CONTROL + SPACE, and select "swap" and in the first set of double quotes, press CONTROL + SPACE and select "troll", then press TAB to move the cursor to the next double quotes (next to o2), and then press CONTROL + SPACE (once again), and select "sleeping_troll).
Finally, press the PLAY icon to test the game.

Important

Once again, objects that are nowhere in the game (not in a location or held by someone, are said to not exist). We can still think of the object, but if the object is not in the game, it does not exist.

Your on_command {} section should look like this (including the entries we made previously):

on_command {

   : match "examine trees; examine tree"  {
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

   : match "examine troll;talk troll"  {
      : if (is_present "troll") {
         : clear_screen;
         : print "\"I'M SO HUNGRY\", says the enormous TROLL in the deepest possible voice." ;
         : press_any_key ;
         : redescribe;
      }
   }

   : match "pick apple;get apple"  {
      : if (is_at "forest" && has_not_created "apple") {
        : print "You take an APPLE from one of the trees." ;
        : pocket "apple";
      }
   }

   : match "give apple"  {
      : if (is_present "troll" && is_carried "apple") {
         : print "The troll grabs the apple from you hungrily. Unfortunately (for the troll), the apple is an ENCHANTED APPLE, and sends the troll directly to sleep." ;
         : destroy "apple" ;
         : swap o1 = "troll"  o2 = "sleeping_troll" ;
      }
   }

}

19. Congratulations

Congratulations, you have coded a simple playable versions of THE CAVE OF MAGIC.

The complete source code for THE CAVE OF MAGIC is as follows.

Read onwards for more information and a additional exercises you may find interesting.

Note	We have built the basic version of the game, without graphics, colour, or inbuilt tutorial. This differs from THE CAVE OF MAGIC DX, which contains full colour graphics and an inbuilt tutorial.

start_at                 = lakeside

locations {
   lakeside     : location "You are by the side of a beautiful lake." ;
   forest       : location "You are on the forest path.\nTall trees tower over you on both sides." ;
   outside_cave : location "You are standing outside the cave of magic." ;
   inside_cave  : location "You are inside the cave of magic." ;
}

connections {

   from, direction, to = [
      lakeside,     north,        forest,
      forest,       north,        outside_cave,
      outside_cave, north_oneway, inside_cave,
   ]
}

objects {
   troll          : scenery "an enormous troll (guarding cave to north)" at = "outside_cave" ;
   sleeping_troll : scenery "an enormous troll (sleeping)" ;
   apple          : object  "an apple" ;
   treasure       : object  "a pile of treasure" at = "inside_cave" ;
}

barriers {

   block_cave : block {
      location               = inside_cave
      message                = THE TROLL IS GUARDING THE CAVE.
      block_when_exists      = troll
   }

}


on_startup {
   : print "You must find the treasure in the cave of magic.";
   : press_any_key ;
}

on_describe {

   : if (is_present "troll") {
      : print "The troll says, \"THE CAVE IS MINE, GO AWAY\"." ;
   }

   : if (is_at "inside_cave" ) {
      : print "CONGRATULATIONS !" ;
      : print "YOU WON THE GAME !" ;
      : print "YOUR RANKING IS : JUNIOR ADVENTURER !" ;
      : press_any_key ;
      : clear_screen;
      : win_game ;
   }
}

on_command {

   : match "examine trees; examine tree"  {
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

   : match "examine troll;talk troll"  {
      : if (is_present "troll") {
         : clear_screen;
         : print "\"I'M SO HUNGRY\", says the enormous TROLL in the deepest possible voice." ;
         : press_any_key ;
         : redescribe;
      }
   }

   : match "pick apple;get apple"  {
      : if (is_at "forest" && has_not_created "apple") {
        : print "You take an <APPLE<12>> from one of the trees." ;
        : pocket "apple";
      }
   }

   : match "give apple"  {
      : if (is_present "troll" && is_carried "apple") {
         : print "The troll grabs the apple from you hungrily. Unfortunately (for the troll), the apple is an <ENCHANTED APPLE<12>>, and sends the troll directly to sleep." ;
         : destroy "apple" ;
         : swap o1 = "troll"  o2 = "sleeping_troll" ;
         : press_any_key ;
         : redescribe;
      }
   }

}

20. Importing Graphics

To add location graphics to the game you must create png files with the same identifier as the location itself.

Note	Location graphics should ideally be in super landscape orientation (3.2 pixels to 1 pixel) so that there is plenty of room for text on the screen.

Adventuron offers two types of import :

Single image file import.
Zipped bundle import.

20.1. Preparation

To demonstrate graphics import, we need some graphics to import.

Ricardo Oyón was kind enough to donate graphics for THE CAVE OF MAGIC.

Click HERE to download the zipfile containing Ricardo’s graphics, for use in this tutorial.

Important

These graphics should not be used in other projects or redistributed elsewhere. They are for the purpose of the tutorial only.

Information of the files contained in the zipfile are found here.

Table 1. Contents of 'CaveOfMagicDXGraphics.zip'
Graphic Id	Filename	Image Type	Resolution	Aspect Ratio
loading_screen	loading_screen.png	Loading Screen	128 x 96	4 : 3
lakeside	lakeside.png	Location	128 x 40	3.2 : 1
forest	forest.png	Location	128 x 40	3.2 : 1
outside_cave	outside_cave.png	Location	128 x 40	3.2 : 1
inside_cave	inside_cave.png	Location	128 x 40	3.2 : 1

Upon import, graphics are base64 encoded and placed into a block of code called assets {}, which will be placed at the bottom of your source code (all the graphics are in the source).

Note	Adventuron adds graphic objects inside the graphics {} block inside the assets {} block corresponding to the filenames inside the zipfile (with suffix removed).

20.2. Graphic Import Procedure

Note	Single image file import is identical but only adds one graphic asset at a time.

Press CONTROL + S to save your game.
Select MENU / Import.

Using the file browser, select the zipfile you want to import (the one we just downloaded).
Now press CONTROL + S again to play your game with location graphics.

20.3. Loading Screen

To set the loading screen, add this line at the top level of your game source code.

This will tell Adventuron which graphic to use as the loading screen (the picture that appears before the game starts).

loading_screen = loading_screen

20.4. Recommendations

If you want to export your game to 8-bit platforms, the recommended image size is 256 x 80 pixels, or 128 x 40. Any resolution is supported, but the 8-bit exporter requires specific resolutions and colour-use.

If you have a project with modern style graphics and you don’t plan to export to 8-bit platforms ( > 50K each PNG), then you should use graphic links rather than embedded graphics (documented in the user manual).

21. Export as HTML

Adventuron allows games to be packaged as standalone HTML files. To compile your game into a HTML page, follow the following steps.

Press CONTROL + S (to save the game).
Select MENU / Compile.

22. Export to ZX Spectrum

To export the game to the ZX Spectrum or ZX Spectrum Next, follow the "Export To 8-bit Platforms" tutorial.

Figure 1. Cave of Magic running under ZEsarUX (ZX Spectrum Next Emulator)

23. End Of Tutorial A

This marks the end of Tutorial A - The Cave of Magic.

Please be sure to check out Tutorial B - Excalibur, which is a larger tutorial that includes concepts such as timers, variables, graphics, and more.

24. Post-Mortem

24.1. Ideas for improvement

If you have reached this far, you should now have an adventure game that is completable without the player having to guess too much (assuming the player knows to use the normal adventure game commands like GET, EXAMINE, and GIVE).

But, even in this small adventure there are lots of things that the player might try to do that the game does not have an elegant way of responding to.

When Adventuron is confronted with a command it doesn’t recognise, it will give a answer such as "You can’t do that." or "I don’t recognise that word." You can reduce the likelihood of this by thinking of things the player might try to do.

Before reading onwards try and think of a few things that a player might try to do in the cave of magic.

Designing a good text adventure game is all about thinking about the player and what they might try to do in your world.

Things that the player might try to do are:

Swim (in the lake).
Throw the apple (at the troll).
Throw the apple (somewhere else).
Eat the apple.
Attack the troll.
Run past the troll.
Sleep.

When you design a text adventure game, it’s important to let the player feel that the game understands their wishes.

The more "responses" to player commands you can code, the more the player will feel connected to your world.

25. Puzzle Dependency Chart

Figure 2. Diagram created with Vizon

Table 2. legend
Box Color	Description
Green boxes	Conditions (passive).
Red boxes	Achievement of a larger goal (passive).
Blue	Player action (active).

26. Video Tutorial

If you would rather watch a video of this tutorial, then it can be found on Youtube (link below):

27. Resources / License

27.1. Tutorial

This tutorial is copyright of Adventuron Software Limited and should not be re-distributed without express consent.

27.2. The Cave of Magic

The Cave of Magic was designed and written by Chris Ainsley is placed into the public domain (excluding graphics).

Remixing The Cave of Magic formed the basis for the Adventuron Cavejam 2019 competition.

Feel free to re-implement or remix in Adventuron or alternative text-adventure engines.

If you re-implement or remix, an acknowledgement is appreciated.

27.3. The Cave of Magic DX Graphics

The graphics in the DX version of the game were created and are copyright of Ricardo Oyón.

Ricardo has licensed the graphics for use with Adventuron’s tooling / documentation but the graphics should not be re-used anywhere else without express permission (the graphics are not public domain).

27.4. Useful Links

Documentation + Videos

Games

List of games made with Adventuron (non exhaustive).

Chatroom

If you want instant support, please use the Adventuron Discord Server.

Forum

If you want to ask questions, the Interactive Fiction Community Forum is frequently monitored. If it is an Adventuron specific question, use Adventuron as the prefix of your subject (or add Adventuron as the tag).

Game Jams

Game jams are game competitions that anyone is free to enter.

Usually they have a theme or a set of rules that each participant must abide by in order to add some structure and to make it interesting.

Adventuron Cavejam 2019 - Remix The Cave of Magic.
Adventuron Halloween Jam - Make a Spooky Game.
Treasure Hunt Jam - Make a text only 'treasure hunt' style game with limited word use.
The Next Adventure Jam - Make a game with graphics using a bright vibrant palette.
An Adventuron Christmas Jam - Make a game with the theme of "Christmas". Ran Nov 17th to Dec 21st, 2020.
Text Adventure Literacy Jam - Create a TEXT ADVENTURE game suitable for children with no prior experience. Lots of prizes to be won including a Raspberry Pi 400 Desktop Computer. Runs Feb 25th to March 31st, 2021.

Text Adventure Literacy Project

The Text Adventure Literacy Project by Chris Ainsley.

Game Design Resources

Puzzle Dependency Charts, the 2014 blog post on how to build puzzle chains by Monkey Island co-creator, Ron Gilbert.
Puzzlon, a puzzle dependency chart creation tool by Chris Ainsley (desktop PC required) Sample Diagram. Please note that Puzzlon does not code puzzles, it only visualises puzzle dependencies, and even though the UI is similar to Adventuron, it is a completely independant system and is open to non Adventuron users.
Text Adventure Design in 2020 by Chris Ainsley.
Look, Search, & Examine by Chris Ainsley.

Other Media Coverage

Go foraging in lovely free text adventure Mushroom Hunt (PCGamer).

Interviews

Interview With Chris Ainsley, Creator of Adventuron Classroom
The Classic Adventurer Magazine by Mark Hardisty (Adventuron interview in issue 5).
(Audio) Adventure Games Podcast (Adventuron Interview).
(Audio) Retro Hour Podcast Episode 238 (Text Adventure History / Adventuron).

Open Sourced Games

Some game authors have released the source code to their games.

Note	Open source is not the same as public domain, be sure to check the game licenses.

Blog Posts

Adventuron Christmas Game Jam Post-Mortem - Save Bigfoot’s Christmas

Pixel Art Editors

Note	Adventuron Draw coming soon.

Graphics must be imported into Adventuron as PNG or GIF files. These external links are provided as a courtesy, please check the individual licenses of these tools.

Browser based :

Desktop based :

http://multipaint.kameli.net (useful for ZX Spectrum, C64, retro compliant images).
https://www.aseprite.org
http://grafx2.chez.com

Visual Studio Code Plugin

Warning

Currently only syntax highlights (colours in the text). Future versions may add autocomplete functionality.

Visual Studio Code is a very popular text editors aimed at coders.

You can find a syntax highlighter for the object notation (used by Adventuron) in the VSCode marketplace, for free - here.

License

Created text adventures can be exported as HTML for non-commercial use.

Games exported to 8-bit text adventure engines are subject to those licenses.

Full details here.

Contact

Adventuron was developed by Chris Ainsley, and is copyright of Adventuron Software Limited.

Full credits are available here.

Email: info@adventuron.io
Twitter - @LearnAdventuron.

28. End of Tutorial A

You have now completed Tutorial A.

Click here to go to the Adventuron User Guide.