WebStory Language Reference
Note: It is recommended that you read the documentation for the available elements.
WebStories are written in a language that was developed specifically for WebStory Engine. The language is both easy to learn for beginners and flexible enough for advanced users.
A WebStory basically consists of one or more story files written in xmugly. Xmugly is a nicer syntax on top of XML. If you're an advanced user, it also allows you to write XML directly.
When you've downloaded and extracted WebStory Engine, you can find some example story files in the story/ folder. The main file is story/game.xmugly and it references the other story files.
Understanding xmugly syntax
Xmugly and XML share some concepts that you should be able to tell apart for understanding this documentation.
Elements and Attributes
An element in xmugly looks like this:
. elementName attribute1 value1, attribute2 value2
An element starts with a dot and has a name (the elementName above) and zero or more attributes. Each attribute conists of a name and a value (e.g. "attribute1" above is the name of the first attribute, and its value is "value1"). An element must always be on its own line and the first non-space character of this line must be a ".".
Elements can also contain text and other elements. Let's look at an example. The following element parent contains some text "This is text." as well as an element child:
. parent :
This is text.
. child
--
Notice that the parent has a colon (":") at the end of its line. This means that this element has some content. The end of the element's content is signaled by the "--" (also on its own line).
Of course elements can have both attributes and content like in this example:
. parent name Mark, age 55 :
. child name Max, age 18
--
Although the attributes of an element are separated by commas, an attribute value can also contain commas if you put it in quotes:
. element attr1 "foo, bar", attr2 val2
In this case, the first attribute is called attr1 and its value is "foo, bar".
Special characters
In XML and therefore in xmugly, there are some special characters that cannot be used in some places. If you want to use such characters, you need to encode them. The following is a list of all special XML characters and how to encode them:
| Character | Encoding | Must be encoded... |
|-----------|----------|-------------------------------|
| < | < | ...everywhere |
| > | > | ...everywhere |
| & | & | ...everywhere |
| ' | ' | ...inside of attribute values |
| " | " | ...inside of attribute values |
Shorthand for attributes
Some attributes are used so often in story files that there's a shorter way to write them. The following is an element with all the shorthand attributes available:
. foo @marc, :200, #marcId, +create, -resize
This is the same as writing:
. foo asset marc, duration 200, id marcId, create yes, resize no
Structure of story files
The main story file (game.xmugly) must be structured as follows:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
. ws :
. settings :
<!-- Section containing general settings -->
--
. assets :
<!-- Section defining the assets used by the WebStory -->
--
. scenes :
<!-- Section containing scenes, which in turn contain the actual commands -->
--
--
The settings element contains general settings for the story such as the width and height of the stage (the part of the site that contains the visible parts of the story).
The assets element contains definitions of the things that are part of the story such as characters and images.
Finally, the scenes element contains all the scenes that make up what is happening in your story. Each scene contains commands (which do something to the assets or the story) and lines (what characters say).
All three of the elements settings, assets and scenes can be written into one or more files. For example, if you want to write all of your scenes in two different files, you can leave out the scenes element from your main story file and instead reference your scene files in the main story file like so:
. file type scenes, url story/scenes1.xmugly
. file type scenes, url story/scenes2.xmugly
This means that all the scenes you have written in the files story/scenes1.xmugly and story/scenes2.xmugly will be included into the scenes element of the main file (and if the main file does not contain a scenes element, it will be created for you).
The default main story file you get when you just downloaded the WebStory Engine package looks like this:
. ws :
. file type settings, url story/settings.xmugly
. file type assets, url story/assets.xmugly
. file type scenes, url story/scenes.xmugly
--
So if you want to change the settings of the story, you change the file story/settings.xmugly. And if you want to add assets, you edit story/assets.xmugly. And you can write your scenes in story/scenes.xmugly.