Wiki

To help anyone thinking of writing a story using Tiny Text Worlds (including me), here is a node by node introduction to the XML file the stories are written in.

#actionPrompt

<actionPrompt defaultText="Choose an action for " />

This node sets the text that appears above the list of possible actions which appear when the player clicks an object with visible actions. Here it is set to "Choose an action for" this will be followed by the name of the object the player clicked. You might want to change this if your not writing the story in English for example. You can set this to "" if you do not want to show this message above the action list.

#cancel

<cancel defaultText="Cancel" />

This is the text for the cancel action that appears at the bottom of the list of possible actions which appear when the player clicks an object with visible actions. Here it is set to "Cancel". You might want to change this if your not writing the story in English for example.

#startUpAction

<startUpAction objectId="exampleObject" actionId="introduction"/>

This is the first action the game will take when it starts up, and must be set for the game to start properly. It can be any action on any object in the xml file. You might like to target an introduction action with a say node which will display some text introducing the play to the game, or you could target an action which does nothing and the game will get leap straight into the first place.

#player

<player location="Place_ID"/>

Here we set the start location of the player. The place name must match one of the names in the places node below.

#userGlobalObjects

<useGlobalObjects flag="false"/>

Setting useGlobalObjects flag attribute to "true" will let you include the global place whose objects will be displayed where ever the player is. This could be used to keep the player aware of their characters state for example. The global objects text is displayed below the text of the players current location.

#places

<places>
    <place id="global" >
        <object id="exampleGlobalObject" />
    </place>
    <place id="Place_ID" >
        <object id="exampleObject" />
    </place>
</places>

The places node contains a list of all the "places" in the world. When the players is in a place the engine will go through all the objects it contains seeing which are visible and have actions the player can use, then displaying a paragraph of text describing the objects and thus our scene. To put an object in a place we just add an object node with it's id to the desired place node.

#objects Inside the <objects> node we put all the objects we will use in our story. Objects can be anything that we want the player to be able to see text for like an apple, table or car or the description of a place.

The first object is the generalActions object which is used by TTW internally, it's best not to alter these. So let's skip them for now.

<!-- System objects used by all worlds -->
<object id="generalActions" name="Hidden" state="start">
    <state id="start"  visible="false">
    </state>

    <action id="ok" name="Hidden" visibleStates="">
    </action>
</object>

Here is the exampleObject from tutorialWorld.xml

<!-- An Example Object -->
<object id="exampleObject" name="ExampleObject" state="start">
        <state id="start"  visible="true">
            <preNameText>This text goes before the name of the object. Then the objectName comes next: </preNameText>
            <postNameText>. Then this text comes after the object name.</postNameText>
        </state>
        ... SHORTENED ...
</object>

Look in the object node's attributes and we find an id which TTW uses to locate it in this xml. This is never seen by the player, and should not be changed during the game. The next attribute is name which is what the player sees if the object is in the same place, and the object is visible. This name can be changed during the game by using a set action. The final attribute is the state attribute this tells TTW the current state id to display for the player to interact with. This can also be changed using a set actions.

Inside the object node are descriptions of that object's possible states. Above we can see the state with id "start" which has a visible="true" attribute. When the exampleObject's state is "start" TTW will look for a state with id="start" for more information. Once found it uses the visible to determine whether to show anything to the player. In this case exampleObjects "start" state has visible="true" so TTW will look inside the state node for test to display. TTW will then displays the preNameText:

This text goes before the name of the object. Then the objectName comes next:

followed by the objects name attribute

ExampleObject

followed by the postNameText

. Then this text comes after the object name.

Which is displayed as one sentence "This text goes before the name of the object. Then the objectName comes next: ExampleObject. Then this text comes after the object name."

#action Objects can have actions which are performed by clicking on their name in the browser. These actions are defined inside the object's node. There is currently no limit to the number of actions that can be defined on an object. There are two actions in tutorialWorld.xml let's take a look at the second action node in exampleObject:

<action id="exampleAction" name="Example action" visibleStates="exampleObject:start"  >
    <say>
        <text>When the exampleAction is clicked. It has a "say" node which prints this text to the screen...
        </text>
     <option type="object" text="OK" visibleStates="*" targetObjectId="generalActions" actionId="ok" />
    </say>
    <set targetObjectId="exampleObject" targetAttribute="state" acceptableStartValues="*" newValue ="notStartAnymore"/>
</action>

Each action has a visibleStates attribute, in this case it is set to "exampleObject:start". visible states are listed as [objectID]:[state] in this case this action is visible when exampleObjects's state is start. We could have multiple visibleStates by listing them like this:

visibleStates="object1:ready object2:ready"

So the action would be visible if object1 or object2 ( made up for this example ) had their states set to "ready".

We can also use && (and) if we need to different object states to have specific states:

visibleStates="object1:ready&&object2:ready"

So the action would be visible only if both object1 and object2 had their states set to "ready".

Finally we can use } ( Used as a stand in for the > greater than symbol) and { ( Used as a stand in for the < less than symbol) to work with numerical states:

visibleStates="score:}5"

NOTE { and } are used in place of < and > as < and > cause parser errors in some browsers.

There are currently two things an action node can do say and set which are described below.

#say

<say>
    <text>When the exampleAction is clicked. It has a "say" node which prints this text to the screen...
    </text>
    <option type="object" text="OK" visibleStates="*" targetObjectId="generalActions" actionId="ok" />
</say>

Say something on screen, and optionally give the user a choice. TTW displays the text from the text node on the screen and below that shows a clickable option for each option node.

TTW displays an option if the objects state matches one of the values in visibleStates this works the same as the visibleStates described under the action heading.

#set

 <set targetObjectId="exampleObject" targetAttribute="state" acceptableStartValues="*" newValue ="notStartAnymore"/>

Set an attribute of an object.

TTW will find the the target object whose id is listed in targetObjectId

Then TTW looks at the targetAtribute of the target object and find what if it matched one of the acceptableStartValues ( * means any value is fine). We can set multiple acceptableStartValues by separating them with spaces:

acceptableStartValues="awake asleep dead"

We can also use } ( Used as a stand in for the > greater than symbol ) and { ( Used as a stand in for the < less than symbol ) to find acceptable values.

acceptableStartValues=}5"

In the above example the current value of the attribute would need to be greater than 5 before TTW would change the target object's attribute.

If the target objects attribute is OK then TTW sets the target objects attribute to what ever we have listed in newValue. We can do basic arithmetic using set by using + or - in the newValue attribute:

 <set targetObjectId="elevator" targetAttribute="state" acceptableStartValues="{3" newValue ="+1"/>

The above example is used on an elevator button which makes the elevator's state increase by 1 each time it's pressed as long as the state is less that 3. See elevator.xml in the bin folder, online version is uploaded here: http://nickholder.co.uk/ttw/worlds/elevator.html .

We can use set to change the state, name and also the players location.