AdvGa

ADVGA is a rewrite of a “gamebook” style adventure game engine I wrote a long time ago. It saw action in an iPhone app called Plot Theft Awesome 5, a light hearted GTAV cash in. This is a complete rewrite that makes it accessible to PCs, Macs, Mobile (iOS and Android) and web scenarios.

Basics

At its most basic, a game is just a list of Pages each containing Texts to describe the story and Options to enable you to navigate the story. A very basic game can be described as such.

GAME::The Demo|The aim of this game is to get out of the room.|Shaun Pryszlak|1.0|true

PAGE::0||
    TEXT::You are in a room and you wish to get out of it.  There is a door and a chair.
    TEXT::You want to get out of there as soon as possible.

    OPTION::Try door|1
    OPTION::Sit down|2

PAGE::1||True
    TEXT::You open the door and leave the room.

PAGE::2|True|
    TEXT::You sit down in the chair and fall asleep.

Simple as that. The first option takes you out the room and triggers the Win condition and the second leaves you in the room and triggers the Lose condition. The uppercase bits and the :: are important. All tabs, leading spaces, blank lines and comments are ignored.

For more advanced stories there are Variable, Expression and Condition. A Variable contains a value and is either a number, a string or a true/false flag. An expression is something like “x|x+1” which when evaluated adds 1 to x. Finally Conditions are things that evaluate to true or false, “x=2” for example. You can add a Condition to a Text block or option so it is only visible if a certain condition is met. For more details of what an Expression can evaluate see here.

TEXT::You are in a room with a big treasure chest.  
TEXT::The key looks like it might unlock the chest
      CONDITION::hasKey=True

OPTION::Open door|1
OPTION::Unlock chest|2
       CONDITION::hasKey=True

There are also Links, Pre and Post expressions. I will get round to documenting those at some point.

Formatting

You can also do some fancy things with the text. Typically all the Text blocks form one long paragraph which is all one colour and style. You can add special codes to add colour, paragraphs, bold, italic, etc.

  • *BOLD_ON* makes the following text bold.
  • *ITALIC_ON* makes the following text italic.
  • *NL* adds a new line character. You use this to divide the text up into paragraphs.
  • *variable name* displays the value of the variable. Mainly just for whole numbers and strings.
  • *RED* makes the following text red. Similar format for green, blue, cyan, yellow, magenta and gray. The game itself is either black on white or white on black.

See the example game for exact usage.

The idea is that the game can be run on any platform and the output will be adapted to match the device. Currently we only have the command line version which can do colours but not bold or italic. A mobile version would probably be based on HTML and therefore display all the styles. As a games writer you don’t really have to worry about what device does what.

Running it

The game is written in Microsofts DotNet. If you are on a PC you should be fine but on a Mac or Linux you will need to download (120 mb) and install something.

Download DotNet

Next you can download the latest version of the game.

Download Game

Unzip it to a folder and look inside. If you are on a PC then run the batch (.bat) file and if you are Mac or Linux ru the shell file (.sh) from a terminal. The same code runs on all the different platforms.

Debugging it

In the batch file you can change the debug parameter to true. This adds a few debugging features.

As you play through the game you are writing, sometimes you want to make changes as you go along. ADVGA has a built in “hot reload” facility. Start playing through the game and at any point you can edit the text file, save it and it will all get reloaded into the game. Simply press “r” at the option menu and it will re-display the current Page. So you can make changes, save, reload, make changes, save, reload and so on.

Also after each Page it displays all the variables and their current values.

Playing it

After each screen you will be presented with your choice of options. You just press the corresponding key on the keyboard (usually 0 to 9). There are a couple of other options.

  • S – Save your current game.
  • L – load your last saved game.

You either win or lose the game. There can be multiple endings of either sort. It is up to you.

The future

If anyone likes ADVGA then I might open source it or something. It would be very easy to create a mobile app for playing these games. There is the possibility of adding sound and pictures but that would need an app to use these features with.