Developer Manual for Version 1.5

Licence

Do whatever you want with the engine, but on your own risk! Anyway, games (story and images) have their own rights.

Basics

WebTale games are made of several locations the player can visit. Each location has a picture, a description text and a list of things, the player can interact with. Furthermore the player can take things (inventory) and use them in other locations or combine them.

In the WebTale language, things are "items" or "objects":

The default actions happen when the player clicks on the name in the list. Other actions appear as buttons.

Engine

In the folder "game" you can find the engine and an example game. To start a new project, make a copy of that folder and work with these files.

The WebTale engine consists of these parts:

XML File

The story (which means all the locations, things and actions of the game) is defined in the file "adventure.xml". It's written in XML format. If you don't know what XML is, please check wikipedia. Use a plain text editor to write this file (e.g. "NotePad" or "TextEdit"), never applications like "Word" (they would save strange files)!

Check the existing XML file to see the basic structure.

There are three types of elements:

In the following descriptions, all attributes between "[" and "]" are optional.

Definitions

<adventure name="name of the game">
This is the root element of the XML file. The name appears as title in the browser window.
<info>
(Inside of <adventure>)
The text of the info box. Line breaks need to be written as "\n".
<text id="…">
(Inside of <adventure>)
A standard text in the language of the game. Standard texts are the default messages, which appear if the player does an action, which is not defined by the story, or texts for buttons in the game. The "%" signs will be replaced by names of items or objects. You can change or translate all texts, but don't touch the "id" attributes and don't remove any element!
<location id="ID of the location" name="name of the location" image="filename of image" [type="person"]>
(Inside of <adventure>)
Definition of one location. Each location needs one <init> and can have several <item>s and <object>s. The ID is an identification for <jump> commands, so there cannot be two locations with the same ID. IDs cannot have spaces and should only use english letters and the underscore (_). The name is shown as title. The image is shown and the file path is relative to the "gamedata" folder.
If the type attribute is set to "person", all items appear in the list with quotes around their names (items are phrases to say then). Furthermore all objects of the inventory get the action "give".
<init>
(Inside of <location>)
Contains commands, which are executed when the player enters the location. Usually this is plain text, which describes the location.
<item id="ID of the item" name="name of the item" [status="hidden"]>
(Inside of <location>)
Defines an item for the location. The ID is used as an identification for commands and has to be unique in the location. IDs cannot have spaces and should only use english letters and the underscore (_). The name appears in the list of things.
If the status attribute is set to "hidden", the item is not shown by default. To make it visible, use the <show> command.
The element contains action handlers for the item. If there is no action handler, the whole content will be used as <onuse> handler.
<object id="ID of the object" name="name of the object" />
(Inside of <location>)
Defines an object for the location. The ID is used as an identification for commands and has to be unique in the game. IDs cannot have spaces and should only use english letters and the underscore (_). The name appears in the list of things.
There is no content in this element. All its action handlers need to be defined globally in <objectdef> elements or location specific in <objects>.
<objects>
(Inside of <location>)
Contains action handlers for objects. They are only used in its location, but have a higher priority than the global action handlers in <objectdef>.
<objectdef id="ID of object" [name="name of object"]>
(Inside of <adventure>)
Contains action handlers for the object. The ID has to be the ID of an object which is defined in any location, or used in a <get> command. If there is no action handler, the whole content will be used as <onlookat> handler.
All objects of the game, which are added by the <get> command, need an <objectdef> with its name. This element can be empty, if no action handlers are needed.

Action Handlers

<onlookat [id="ID of thing"]>
<onuse [id="ID of thing"]>
<onusewith id="ID of second thing">
<ongive id="ID of object">
(Inside of <item>, <objects>, <objectdef>)
All action handlers can contain commands and/or plain text. When the player does an action, the corresponding handler will execute its content and/or show its text.
If an action handler is inside of an <item> or <objectdef> definition, don't use the id attribute, because the handler already belongs to it. The only exception is <onusewith>, because the ID is of the second thing the player clicks on.
If an action handler is inside of <objects> in a location, you have to put the id attribute with the ID of an existing object. The <onusewith> handler cannot be used inside <objects>.
<onnoneed>
(Inside of <objects>)
This is a special action handler, which is used when the player tries to give an object to a person and for the object there is no <ongive> defined. It's usually a plain text like "I don't need this" in the talk style of the person.

Commands

All commands have the optional attribute "if". This means, the command is only executed, if the expression in the "if" attribute is true. Expressions are explained later.
If you write plain text instead of a command, it is added to the text area of the game. Line breaks have to be written as "\n", breaks in the text editor are ignored.
<jump to="ID of location" [if="expression"] />
Makes the game continue in another location. If this command is executed, following commands will be skipped.
<do if="expression">
Contains actions which are only executed if the expression is true. Usually contains plain text, because other commands already have their own "if" attribute.
<get id="ID of object />
Adds an object to the inventory. If an object with this ID is in the current location, it will be removed from there. If the object is not defined in any location, it needs an <objectdef> to define its name.
<drop id="ID of object" />
Removes the object from the inventory.
<show id="ID of item" [location="ID of the location"] />
Makes an item with status="hidden" visible. This status will stay, even if the player visits other locations, until <hide> is called. If the location attribute is not set, the current location will be used.
<hide id="ID of item" [location="ID of the location"] />
Hides the item. This status will stay, even if the player visits other locations, until <show> is called. If the location attribute is not set, the current location will be used.
<set var="name of variable" [value="number"] />
Sets the variable to a number. If no variable of this name exists, it will be created. If no value is given, the variable is set to 1. Variable names cannot have spaces and should only use english letters and the underscore (_).
<add var="name of variable" [value="number"] />
Adds the given value to the current value of the variable (negative values can be used to subtract). If no value is given, 1 is added. If no variable of the name exists, it will be created with the given value (or 1, if no value is given).
<showimage file="filename of image" />
Changes the current image to the given one. The file path is relative to the "gamedata" folder.
<share title="title text" text="detailed text" picture="complete URL of an image file" />
If the game runs in a social network (e.g. Facebook), this will open a "share" dialog. Otherwise the command is ignored.

Expressions

Expressions are written inside of "if" attributes and are resolved in true or false. For information about variables, see the commands <set> and <add>.

"X"
X can be a number or the name of a variable. If the value is 0, the result is false (unexisting variables are 0, too). All other values are resolved in true.
"not X"
Works like "X", but with the contrary result.
"has X"
X is the ID of an object. If the player has this object in the inventory, this expression is resolved in true, otherwise in false.
"hasnot X"
Works like "has X", but with the contrary result.
"X is Y"
X and Y can be numbers or names of variables. If both values are equal, the expression is resolved in true, otherwise in false.
"X ismin Y"
X and Y can be numbers or names of variables. If X is equal or bigger than Y, the expression is resolved in true, otherwise in false.
"X ismax Y"
X and Y can be numbers or names of variables. If X is equal or smaller than Y, the expression is resolved in true, otherwise in false.
"X isnot Y"
X and Y can be numbers or names of variables. If the values are unequal, the expression is resolved in true, otherwise in false.

Server and Social Networks

Starting with version 1.4 it is possible to store the user's savegames on a server (requires PHP and MySQL). To make this possible the game needs to run in an environment where the user is logged in, because the server needs a unique user ID. The engine is prepared for Facebook, but can be extended for other platforms, too.

Preparing the Server

Create a database in MySQL and then execute this SQL code to create the table:

CREATE TABLE savegames (
game_id VARCHAR(30),
user_id VARCHAR(30),
data_json TEXT,
CONSTRAINT pk_savegames PRIMARY KEY (game_id, user_id));

Then edit the file "server/serverconf.php" and put the correct values to access the database.

Preparing the Game

In "gamedata/adventure.xml" you have to define <serverurl> and <servergameid>. The first has to be the URL of the server directory (where the PHP files are). The second should be a short name of the game (e.g. "myadv1"). With the game ID it is possible to use the same MySQL table for different games.

As soon as these values are defined in the XML, the game will not store savegames locally in the browser anymore. But to enable the Load/Save buttons, the user ID needs to be set. In the "index.html" of the game exists prepared code for Facebook. If you want to use it, remove the lines <-- and --> from around the JavaScript part. There are several places with "YOUR_APP_ID" and "YOUR_APP", which need to be replaced with the real values of your Facebook application. The JavaScript part for Facebook also sets the function to open "share" dialogs.

Other Environments

If you don't use Facebook, you can delete the JavaScript code for it from the game's "index.html". To enable storing on a server you have to provide a user ID (can be a string) by calling setUserId(uid). If it's a social network and you want to be able to share "stories" on a wall, you have to implement a function like "share(title, text, picture)" and call setShareFunction(function).