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.

First game written using it is Rogue Life.

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 (starting with an #) are ignored.

For more advanced stories there are Variable, Expression and Condition commands. 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.

For more details see the AdvGa Commands page.

Finally there is a file called Character.txt that contains a few variables that can be used to describe yourself. If desired, these can be referenced in the games to make you the star of them. Make it a bit more immersive.

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* splits any following text into another paragraph.
  • *variable name* displays the value of the variable. Mainly just for 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) run the shell file (.sh) from a terminal. It is the same command to run it whichever platform and the same code runs on all the different platforms.

dotnet AdvGa.dll –file-name=games/basic_game.txt –debug=false –compact=true –darkmode=true

–file-name is used to specify which game to run.

–debug=false turns debugging on or off.

–compact=true makes the text wrap at half the width of your terminal window.

–darkmode=true makes it display white text on black while false makes it display the other way round.

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.
  • X – Exit the 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.