Building Text Adventures For The Next With Adventuron

About Adventuron

Adventuron ( https://adventuron.io ) is a text adventure authoring system that runs inside the browser. Adventuron is a database-based adventure game engine, and anyone familiar with QUILL or PAW should feel right at home.

Adventuron’s engine (in the browser) runs in JavaScript (boo), but functionality was recently added so that Adventuron games written in “8-bit-compatibility-mode” can export games to a variety of 8 (and 16 bit) platform’s via Tim Gilbert’s DAAD system, together with UtoDev’s Maluva plugin.

Rite of the Druid for the next was recently coded using Adventuron, and it’s possible to put together quite large and complex adventures using the system.

Whilst Adventuron in the browser has no arbitrary size limits, Adventures (on ZX Next) can contain approximately 96K (compressed) of text and logic. Up to 255 location graphics are supported. 512 colour graphics at 256 x 80 are recommended, as used in Rite of the Druid.

Now we have that out the way, this article will demonstrate how to create a small introductory adventure game using Adventuron, targeting the ZX Spectrum Next.

Getting Ready

In order to follow this tutorial, you should download and install DAADReady 0.2. Unzipping this file ( http://ngpaws.com/downloads/DAAD/DAADReady/ ) into a DAADReady folder is all that is required for this step.

locations {}

The locations {} section is where Adventuron stores the locations that will be used in the adventure. In the cave of magic, we define 4 locations, the lakeside, the forest, outside the cave, and inside the cave.

Every element in the locations section has an id (e.g. lakeside), a type (location), and a description (the part that will be printed).

Every Adventuron game needs a start location too, so we define the start location in the ‘start_at’ attribute, usually at the top of the source code.

connections {}

The connections {} section is where we connect locations together. Connections have three elements per line, the
FROM location, the DIRECTION, and the TO location.

When defining connections, ignore any blocks that you might want to apply later in the game. Directions are bi-directional by default, meaning that if the lakeside leads north to the forest, we can imply that the forest leads south to the lakeside.

objects {}

The objects {} section is used to store objects we require in the game. There are two types of object. A scenery object is for objects that cannot be picked up, and a regular object “object” is used for objects that can be picked up and taken by the player.

We can use the “at” attribute to specify where the object will be at the start of the game.

Not shown here, but if an object has a static (non context sensitive) examine message, you can use msg=”Your examine message here” on each object to specify the examine message. Examine messages can be configured in the on_command {} section too (shown later).

on_startup {}

The on_startup {} section is executed when the game starts, but before the first location is described. We can use this to display the goal of the game and / or the game credits.

This is the first example showing commands. There are many commands that are supported in Adventuron. The two commands used here are “print” – which prints some text to the screen, and “press_any_key” – which waits for some user input.

A clear_screen is always performed after the on_startup {} block is executed, and then the start location will be printed, and the game will start proper. Feel free to experiment. A good thing to try is excluding the press_any_key line and see what happens.

on_describe {}

The on_describe {} section is executed every time a location is described (either by entering it from another location or by the player typing LOOK or R).

There are two core pieces of logic in here.

1. If the troll is present when the location is being described, then print out a message that tells the player that the cave belongs to the troll so the player should go away. This is not strictly necessary but without flourishes like this,  the troll would seem lifeless.
2. If the player is inside the cave of magic, then print some messages to tell the player that they have won the (very short) game, and then wait for the player to press a key, then clear the screen and tell adventuron that the player won the game (will reset the game to play again).

barriers {}

Barriers block access between two or more locations.

There are three types of barrier.

• A block, which block access to a location from any direction.
• A block_path, which blocks access between two specific locations.
• A door, which is an openable, closable, lockable door between two locations.

A block tends to have a message, and an activating condition. It could be a boolean variable (true or false variable).

In the example show above, the barrier is active when the (non-asleep) troll exists.

on_command {}

The on_command {} section is used to check for specific text patterns that the player might enter into the command line, and to process that text in the context of the game state.

There are four key VERB NOUN combinations we need to capture for this game.

1. If the player types EXAMINE TROLL or TALK TROLL and the troll (non asleep troll) is present in the current location, then clear the screen, and print a message telling the player that the troll exclaims it is hungry. Wait for a keypress, then redescribe the current location. This examine/talk message is important so the player has a clue how to remove the troll as a barrier.
2. If the player types EXAMINE TREES or EXAMINE TREE or LOOK TREE or LOOK TREES (examine and look are synonyms), and if the player is in the forest location,
   print out a message that tells the player that the trees are apple trees. This tells the player that they might be able to try and get an apple (for the troll).
3. If the player types PICK APPLE or GET APPLE and the player is in the forest, and the apple has never been created before, then create an apple in the player’s pocket, and print a message telling the player that they picked an apple.
4. If typing GIVE APPLE or THROW APPLE when the (non asleep) troll is present and the apple is carried, clear the screen, print out a message that tells the player that the apple sends the troll to sleep, and swap the troll for the sleeping troll, then wait for a keypress, then after the player presses a key, redescribe the current location.

Importing Graphics

To import graphics into Adventuron select the MENU / IMPORT option. Your graphics should be PNG files that are 256 x 80 pixels, and should be 256 colours or less (if targeting ZX Next) or ZX Spectrum compliant if targeting +3 (edit with Multipaint to ensure this).

The names of the PNG files should match the identifiers of your locations (e.g. if you import a file called “lakeside.png” then after import it will automatically be displayed when you are in the lakeside location.

Adventuron can bulk import graphics using a zip file. For this tutorial, to import (ZX Spectrum Next) compatible graphics (created by Ricardo Oyon), first download graphics from https://adventuron.io/graphics.zip to your downloads folder, then use the IMPORT menu option and select the graphics.zip file from your downloads folder. Four graphics will be imported (one for each location of the tutorial game). Feel free to examine the structure of the zip-file to learn how to use this shortcut in your own games

Exporting to DAAD Ready

To export your game to DAAD Ready format, simply select the MENU / Export DAAD (+ Graphics) from the Adventuron Menu. It will create a zipfile in your downloads folder.

Building the ZX Next Bundle

1. Unzip the contents of the zip file created by Adventuron to your DAAD Ready folder. Adventuron will use the name TEST.DSF for the emitted game source-code by default (inside the zip), so every time you have a new version of your game to test, overwrite the existing source.
2. Create a command prompt whilst inside the DAADREADY folder, type ZXNEXT.BAT to build (and test) your ZX Spectrum Next image.
3. Running the BAT script above will not only compile your game, but it will also run the Next emulator that will test your game. You usually have to press a key to launch the emulator after compiling (see screenshot).
4. When finished testing, close the emulator window, and this will bring back the prompt in your command window.
5. Repeat this process as you develop your game.

Your compiled .TAP file file will be created in the RELEASES/ZXNEXT subfolder.

For an example of how to distribute a game made this way, search for “Rite of the Druid ZX Next” with your favourite search engine, and download the distribution there for reference.

NOTE: As a general rule DO NOT customise the emitted source-code without renaming it first. Typically you will have no need to manually edit the TEST.DSF file.

Find Out More

To find out more, feel free to check out the tutorial at https://adventuron.io/documentation/tutorial-a.html.

NOTE: A version of this article was previously published (by the same author), in The Spectrum Show magazine, issue 31.