Here we dive into some proposals for the file format of the GpsQuest universe.
I'd like the quests to be runnable offline, that means no roaming charges, no unpredictable internet connectivity, less power drain and no restrictions. If you download the quest, then you can go offline and just use the GPS, you have all the data and media you need. I'd propose a filename of "something.quest" which is actually a zip container, very similar in idea to an epub or odt or kmz or other such archives. This has advantages of being portable, compressed, and very editable. Until the builder tool is available (much later), the files can be edited, collected and zipped and you have a quest.
So what's inside the .quest file? Mainly a single xml file, with some standard name (maybe main.xml). This contains all the definitions of the quest including all texts, messages and logic, in a simple readable, editable file. Any image files and audio files are just referenced by filename, and they are also packed into the same zip container along with the xml, something like this:
Zip container |- main.xml +- res |- image1.jpg +- image2.jpg
Here the proposal is a res directory (for "resources"), containing all the referenced media files. Probably a limited number of media formats would be supported, like jpg, png, ogg and mp3.
Important here is that there is no reliance on any obscure programming language such as lua — no weird compilers to use, no incompatible language versions, no incompatible bytecode interpreters on different Android versions, no security implications of loading untrusted bytecode. And no platform-specific Quests, there's just one Quest for every device (PocketPC, anyone?).
Every detail of the quest is held in the single "main.xml" file, split into sections:
<Quest> <Head> This includes basic details such as name, id, start coordinates, description, author and supported languages. It also defines a list of variables which get updated during the quest, defines timers if necessary, and specifies with which <Scene> object the quest should start. </Head> <Zones> This defines all the geographical zones in the quest, where something could happen when you enter or exit them. They can be either a single point (with a radius) or a convex polygon defined by a series of points. </Zones> <Triggers> This defines a series of triggers, which check the values of variables and then determine whether to set other variables or go to another specific scene. Triggers can be activated by entering or exiting zones, or by timers firing. </Triggers> <Scenes> A list of scenes, each of which can contain text, images, "OK" dialogs, multiple choice questions and text-entry questions. </Scenes> </Quest>
Some of these details can be expanded as the definitions become clearer. Importantly the quest file is versioned, so any changes to the specification can be handled by increasing the version number and expanding the associated tools accordingly.
The next step is probably to define this xml structure using an .xsd to enable quick and easy validation of a quest file to ensure that it's valid.
Unsupported in version 1 is any kind of enemy objects, any kind of shooting, any kind of video (but perhaps support for animated gifs would come for free), and any kind of mobile zones. Although you could easily have multiple zones activated and deactivated by timer to simulate the movement of a game character from place to place.
The standard items in the <Head> of the xml file describe the quest's main properties, like this:
<Head> <Name>Name of the quest</Name> <Version>1.0</Version> <Id>Unique identifier assigned by central repository?</Id> <Description lang="en">Description in specified language</Description> <Author>Identifies the author</Author> <StartCoords lat="0.000" lon="0.000"/> <Variables> <Variable id="XYZ" value="0"/> ... </Variables> <Timers> <Timer id="DEF" period="5" trigger="T4" repeating="false"/> ... </Timers> <StartScene id="S0"/> </Head>
Here the option to provide a cache description in any number of languages is provided, so the same quest can be done in multiple languages. There can be any number of <Variable> elements with different names, and variables don't need to have a type assigned, so they're all strings.
There isn't an inventory explicitly defined here, but possession of a particular object can be indicated by setting the corresponding variable value to "1", and non-possession by "0".
Multiple timers can be defined, and all are by default off until they are explicitly started. Timers can repeat if desired, and simply activate the specified trigger when the timer expires.
Units of the file are fixed, so latitudes and longitudes are always in +/- decimal degrees, and timer periods are always in seconds. Similarly, distances will always be specified in metric metres. Of course the mobile app can present this information however it likes!
Each zone in the quest is defined in advance and has a fixed position. Of course, whether anything happens when you enter it will depend on the trigger, which can decide to do nothing if the variables don't match the conditions (eg you haven't collected an item, or haven't activated a switch, or haven't already been to the library):
<Zones> <Point id="P1" lon="0.500" lat="0.500" radius="50" enter="T1" exit="T2"/> <Polygon id="P2" enter="T3" exit="T4"> <Node lon="0.2" lat="0.1"/> <Node lon="0.3" lat="0.1"/> <Node lon="0.3" lat="0.15"/> ... </Polygon> ... </Zones>
This example shows two zones being defined, the first one P1 defining an area of 50 metres radius around the given point, and the second one P1 defining a triangle consisting of three nodes. The four triggers T1 to T4 reference Trigger elements in the following section, which may do nothing or they may progress the quest.
It's likely that the edges of the zone will have a kind of blurry boundary, in that you have to get quite close inside the zone's boundary to trigger the enter event, but then retreat a certain distance back outside the boundary before the exit event is triggered. This "hysteresis" effect will avoid the problems which can occur when you stop moving immediately upon entering a zone (obviously, because you want to find out what has just happened) but then measurement error right on the boundary causes the phone to think that you're back (slightly) outside the zone again. This mechanism can be dealt with much later when the code is actually on the phone.
Each trigger can have several conditions which must be met, and if all of them are true, then the associated action is carried out:
<Triggers> <Trigger id="T1"> <Condition var="A" value="1" comparison="eq"/> <Condition var="B" value="0" comparison="ne"/> <Action> <SetVariable var="C" value="2"/> <GoToScene id="S1"/> <StartTimer id="DEF"/> </Action> </Trigger> </Triggers>
This example is equivalent to the logic that if trigger "T1" is fired, either by entering or exiting a zone, or by a timer expiring, then it checks if the value of variable "A" is equal to (eq) 1. If so, and if also the value of variable "B" is not equal to (ne) 0, then the action is carried out. In this case, the variable "C" is set to the value 2, the quest proceeds to scene "S1", and timer "DEF" is started.
Possibly the Trigger will also need the ability to increment the value of a variable, or add or subtract values. Or possibly this can be avoided for version 1 and added later if needed.
The format of the Scenes is a little trickier to define, as they need to be flexible enough to contain text messages, 'OK' buttons, graphics (using the included resource files), questions with 'Yes' and 'No' buttons or other multiple choice options, and perhaps also questions with free-format text entry answer fields.
This is the part which will be most subject to change before (and after) the release of version 1, if potential authors hear about the Quests and request additional features.
One thing that will definitely be required here is multiple language support, so the same Quest can be attempted in different languages. The logic would be exactly the same for all languages (defined by the Timers and Triggers in language-independent form), but the text messages and buttons and graphics could all be customised for whichever languages the author chooses to support.