Mark Damon Hughes  | GameScroll: README
Table of Contents
#Starting GameScroll
#What's New?
#Future Plans
    #System Variables
    #Basic Commands
    #Programming Commands
        Math Commands
        String Commands

Copyright 2002-2005 by Mark Damon Hughes <>
All Rights Reserved
LICENSE: You may download and use GameScroll free of charge, and you may include GameScroll with your adventures. You may not modify or decompile the software. If you redistribute GameScroll, you must include all of the files of the original distribution completely unmodified. The original distribution of GameScroll can always be found at

Starting GameScroll

Windows, MacOS X:
Double-click on GameScroll.jar
Linux, Unix:
./ []

What's New?

Version 0.7 (released 2005May03)
Version 0.6 (released 2005Apr25)
Version 0.5 (released 2005Apr20)
Version 0.4 (released 2004Feb17)
Version 0.3 (released 2004Feb14)

Future Plans

The development path up to 1.0 looks pretty clear, now:

Planned for 0.8
Graphical adventure editor, instead of writing XML by hand.
Planned for 1.0
GameScroll 1.0 will be released when all the previous features have been playtested properly.


To create an adventure, copy to whatever you want to call your new adventure, open it in a programmer's text editor, and modify it. Crawl is a not much of a game, but it demonstrates all of the basic features of GameScroll. All adventures must have the .gs.xml extension.

If you have images and sounds to add to the game, create a directory with the same base name as your adventure ("crawl" for "", etc.), and put all of your materials in there; this way, you can develop many adventures separately. The "images" and "sounds" directories and files GameScroll comes with should not be modified.


Below is a quick reference list of all of the tags and their syntax. A more detailed and friendly description is below in Basic Commands and Programming Commands.

[] optional element (so "foo[bar]" means either "foo" or "foobar")
IF ifvar="VARNAME" [[ifop="OP"] ifvalue="VALUE"]
ID any characters *except* the surrounding quotes (either " or ') or {}.
TEXT any legal XML text. Text may contain variable references in the form "${VARNAME}" which will be replaced with the value of the variable. If the variable is not defined, "${UNDEFINED VARNAME}" will be inserted instead.
N any integer value from -2147483648 to 2147483647. N may contain variable references.
BOOL boolean value, "true" or "false".

System Variables

Several variables are defined by the system. These should not be modified by your adventure:

${PAGE} The id of the current page. Using <call> to visit a page temporarily does not set ${PAGE}.
${SCORE} The current score.
${TURN} The number of choices made.

Basic Commands

Every GameScroll adventure must start with these two lines:

And must end with this line:

The version ID must be the version number of the copy of GameScroll you wrote it with: 0.5, 0.6, and so on. If the scroll is loaded in an older version of the software, an error will be given. If it is loaded in a newer version, that's fine. This allows you to have forward compatibility of your adventures. Your older adventures will always work in later versions.


In between are the pages. An adventure consists of many "pages", each of which has a unique name, and can show text and have one or more choices to go to other pages. A new page is started like this:

And ends with:

ID is replaced with whatever you want to name the page. The first page in an adventure must be named start.

If save="true" is given, then the user can save on that page. If save="false" is given or save is not defined, the user cannot save.

Within each page (between the <page> and </page> tags), you can have any number of commands.

If there is a page in the adventure named score, that page will be displayed instead of the standard "Your score is ${SCORE} in ${TURN} turns." message. You should never send the player to the score page, and there should be no choices on it. To make a character sheet with layout, use a table:

As the example shows, you can build up pieces of HTML markup to insert into a larger structure.


The text command looks like this:

"[IF]" will be discussed below, don't worry about it just yet. TEXT can be any plain text or XHTML markup.

To show a simple room description, you could write:

Text can be given different styles by wrapping it in <b>boldface tags</b>, <i>italics tags</i>, <u>underline tags</u>, <big>big tags</big>, <small>small tags</small>, <font color='red'>color tags</font>, or any other legal HTML markup.

To insert a line break, use
<br /> at the start of the line, or

<p>wrap the entire paragraph in paragraph tags</p>

You cannot use the characters < > or & as plain text, because they indicate XML and XHTML markup. Instead, use &lt; &gt; and &amp; to insert these characters. The semicolon at the end is essential!


The choice command looks like this:

You replace the href ID with the ID of another page to go to, while the TEXT is the option shown to the player. So a typical corridor could be written as:


The gameover command looks like this:

When the gameover command is executed, the game ends and the player's score is shown. Note that any commands after the gameover are not executed. The following set of commands will not print "Just kidding.":


The score command looks like this:

When executed, it adds N to your current score. N must be an integer value (no fractions!) from -2147483648 to 2147483647 (it's a 32-bit number). To reward the player, use a positive value; to penalize the player, use a negative value. You can use score as experience points, or just as an abstract game score.


The img command looks like this:

img displays an image, usually from the local filesystem. To do this, use a URL of "file:FILENAME", or "file:DIRECTORY/FILENAME". Slashes between directories must be forward slashes (/) not backslashes (\), even on Windows. img can support http: URLs, but except for adventures intended to have dynamic content, you should include all necessary images with the adventure.

Assuming scroll.png is in the same directory as the adventure, this displays the image:


The sound command looks like this:

sound plays a sound sample in .wav, .au, or .mid format, usually from the local filesystem. To do this, use a URL of "file:filename.wav", or "file:images/filename.wav". Slashes between directories must be forward slashes (/) not backslashes (\), even on Windows. sound can support http: URLs, but except for adventures intended to have dynamic content, you should include all necessary sounds with the adventure.


Custom commands are almost identical to pages:

'id' is the name of the command, and 'desc' is the full text description given in help.

Within each custom command, you can have any number of commands. If a command should move the player to another page, use <clear /> to remove current choices and <choice> to add a single choice for the new destination.

If a custom command should not be usable until some condition has been met, make the first command in it a test for that condition:


Clear deletes all existing choices. Always add another choice afterwards, or the player will be unable to continue!


Comments do nothing, but allow you to leave an explanation of a page or command for yourself. XML comments <!-- TEXT --> will work in hand-edited pages, but will be lost by the graphical editor. The comment command will be preserved by the graphical editor.


The map command adds a 32x32 pixel image tile and/or text to the player's maps. As the player explores the game, new tiles can be revealed.

The player has multiple maps, identified by 'id'; the traditional overall map is id='map', and additional maps can be added as the game progresses. Only the current map is shown.

The size of each map is determined by the furthest x,y coordinates placed. Coordinates start at the top-left corner as x='0' y='0', and increase down and to the right.

If TEXT exists, it will be drawn centered on the given tile. If color is specified (as an HTML hex color: #RRGGBB), the text will be drawn in that color; if it is not specified, it will be white.

'tile' can be in two forms: "FILENAME" or "FILENAME,COLUMN,ROW". The first just uses a single image file for the tile. The second uses a "tileset", an image containing many tiles in a grid. For instance, "images/dg_features32.png,0,5" is a grass tile, while "images/dg_features32.png,3,0" is a stone wall.

You can use the standard art, or provide additional art with your adventure. The dg_ tilesets are free art created by David Gervais. Thanks, David!


mapat sets the "You Are Here" marker (a golden @ ("at") sign) in a specified map grid.

Programming Commands

The remaining commands are not needed for basic adventures. Feel free to skip this section if you don't feel up to it.


All of the commands allow you to add an if-expression to them, which executes the command only when the if-expression is true, and skips it if false. There are three forms of if-expressions:

The ifvar must be present to have an if-expression. This is the name of a variable (assigned with <set>) to test. Don't include the ${} around the variable's name!

If ifvalue is not defined, the value of ifvar is tested. If it's completely empty (not even any spaces) or is 0, then the if-expression is false and the command is skipped. Otherwise the command is executed.

If ifvalue is defined but ifop is not, ifop is assumed to be "eq" (Equal To).

If both ifvar's value and ifvalue are integers, they are compared numerically; otherwise, they are compared alphabetically. The comparison is case-sensitive.

The ifop is the comparison operation to use:

eq Equal To
ne Not Equal To
lt Less Than
le Less Than or Equal To
ge Greater Than or Equal To
gt Greater Than
range Range: ifvalue must be in the form "INTEGER..INTEGER", and will be true if ifvar is between the two integers, inclusive.

For instance, in the following, only the (true) lines will be displayed:


The set command looks like this:

What this does is assign the TEXT to a variable named ID. You can then call that text back up in any TEXT or attribute field of any page by writing ${ID}. For instance:

Or using it in an attribute:

You can have an unlimited number of variables. If you attempt to use a variable ${foo} that is not defined, the text ${UNDEFINED foo} will be inserted instead. You should always define all variables in your start page.


input looks like this:

Input displays TEXT as a prompt, then reads a line from the player and stores it in the variable ID. Input can be used to ask for a character's name or ask other non-multiple-choice questions, such as riddles. If you are asking for a riddle answer, don't make it impossible for the player to type: simplify it down to a single word, and convert it with <lower> before comparing it:

Math Commands

add, sub, mul, div, mod

Math functions look like this:

These commands convert the current value of variable ID and TEXT to numbers, add, subtract, multiply, divide, or modulo (remainder) them, and assign the result back to variable ID.

add provides a useful way of checking multiple conditions:

String Commands

indexof, left, right, len, lower, upper

indexof finds the position of TEXT within the contents of variable ID, or 0 if not found, and assigns the result back to variable ID.

left and right convert TEXT to a number, and set variable ID to the left-most or right-most TEXT characters in the current contents of variable ID.

len finds the length of TEXT, and assigns the result to variable ID.

lower and upper convert the current value of variable ID to all lowercase or uppercase, and set variable ID to the result.


rnd converts TEXT to a number, and then sets variable ID to a random number between 1 and TEXT, inclusive. If 'n' is set, then it is converted to a number, and that many random results are totalled up.

For instance, to roll three six-sided dice:


call jumps to a page given as href, evaluates all of the commands on that page as if they were in the current page, and continues on in the current page. If you are familiar with programming languages, call is like "gosub" or a function call.

call can be used to add a standard bit of processing that will happen in many pages. For example: adding 1 to a hunger_turns variable, checking for hunger_turns being over some limit, and offering to let you eat rations if you are:


end stops reading the current page without processing the remaining commands and returns to the call command or prompt. This can be used to select from a range of values with if:

iOS Games & Utilities: [Brigand] [Perilar] [Castles] [DungeonDice] [UnixTime] [Notecraft] Computer Games: [Dormanica] [Aiee] [GameScroll] [Hephaestus] [JPerilar] [Umbra] Utilities: [JICB] [Javascript]
Copyright © 2007 by Mark Damon Hughes  |  email