TheoWorlds Builder SDK v2 Documentation

Graphic Libraries

1. TIE map objects and libraries

Theo Isometric Engine (TIE) maps can contain three types of map objects: floor tiles, furniture and characters.

Map objects are organized in libraries. You can see the libraries that come with this SDK in the "library"folder - they are called floor.xml, furniture.xml and characters.xml. A library is basically an XML file that lists the map objects of one type.

This is how floor.xml looks like:

<?xml version="1.0"?>


<library id="1">
 <items>
 
 

 
 
 ...
 </items>
</library>

The line in bold represents one map object - in this case a floor tile. The main attribute, called "url", is the location of the SWF file that contains the image of this object. Other attributes are described below.

TIE can use multiple libraries, which makes it very flexible - you can assemble map objects into different libraries, using just the ones you need.

Do not mix map objects of different types inside one library.

2. Maps, libraries and maps objects

TIE maps are defined as XML files that contain the map parameters and also the list of the objects that are placed on the map. Those XML files can be generated using Map Editor or simply modified by hands in any text editor. Below is an example how maps, libraries and map objects interconnect:

Maps and Libraries

When a TIE world is created it loads the map file - "maps/chat_apartment.xml" in this example
The map file contains the list of all the libraries that need to be loaded - in this example "library/furniture.xml" is one of these libraries
The map file also lists all the map objects that have to be placed on it - it points to the library ID and the object ID in this library
The map object details are stored in the library file - furniture.xml in this example. The most important parameter defined in the library for each object is the location of the graphic SWF file that contains the image of the object - "library/furniture/i009.swf" in this case.

2. Floor tiles and Furniture

Each floor tile and furniture object has to be placed in a separate SWF file, which is linked from the library XML file. You can find the source FLA files for the objects that come with this SDK in "library/fla" folder.

The structure of a floor tile or a furniture SWF file is the same - it's a simple movieclip with one or more frames. The guidelines intersection indicates the middle of the map tile so you can align your object properly.

You can have multiple variations of the same object, mostly used for storing object images that point in different directions (up to eight).

Once you created the SWF file, you have to point to it from a library. Here is an example:

Here are all the parameters that can be defined for a floor tile:

id - an unique ID number. Mandatory attribute.
url - the path to the SWF file containing the floor tile image. Mandatory attribute.
stackable - a flag that defines if other objects can be stacked on top of this object. Can be "0" or "1" and, if skipped, "1" is the default value (stackable)
elevation - a number that defines the height of the object in pixels. It's used for calculating the elevation of the objects that are placed on top of it. Optional. 0 by default.
walkable - a flag that defines if the tiles occupied by this object are walkable or not. Can be "0" or "1" and, if skipped, "1" is the default value (walkable) for floor tiles and "0" for furniture.
direction - a number that defines the frame of the map object SWF file, in case there are multiple frames (mostly used for multiple directions of the same object). If skipped 1 is used as a default value.
objectShape - if the object occupies more than one tile (maximum 3x3) we need to specify which tiles it exactly covers. In order to do that, imagine the 3x3 tiles as an array with occupied tiles marked with "1" and non-occupied ones marked with "0". objectShape is a string that lists all those 1's and 0's in one line, with a space to separate the rows. An object that is 3x3 tiles big and occupies all 9 tiles will have objectShape="111 111 111". Note that when you place the object in isometric space, it looks like it was rotated clockwise and the direction of the object is from top right corner to the bottom left one.

In the examples below the objectShape will be "111 100 000" and "110 110 110" respectively. The trailing 0's in each line can be skipped, so "100 100 100" is the same as "1 1 1". For the second image below it can be "11 11 11" for short.

Map Object shape

animation - not used at this point (reserved for future optimization).

The furniture map objects share the same parameters, except objectShape, plus an extra one:

selectable - a flag that defines if the furniture object is selectable. Can be "0" or "1" and, if skipped, "0" is the default value (not selectable)

2.1 Tiles and furniture triggered actions

You can assign a specific action to a tile or a furniture object in order to trigger it once the character steps on it. Check demo#8 for an example of tiles and map objects that trigger the character to jump over them: http://www.theoworlds.com/labs/08/.

An example of a furniture/action combo is the chair - it triggers the character sitting animation when the character reaches it.

We will explain it using the teleports - tiles with actions that make the character "jump" to another map. Here is an example of a teleport (a fragment from a map XML file):

<f col="17" row="10" libID="2" libItemID="66">
 <actions>
 <a name="teleport" destRoom="Dance Club" destTile="9,42" />
 </actions>
</f>

There are two different places to add an action to a map object: through the library XML or through the map XML:

1. Assigning the actions directly through the library XML. Let's say we have a simple furniture map object and here is description in the library:

 ( walkable="0" by default)

This furniture image looks like an animated arrow. If we set walkable=1, we will allow the character to step on those arrows:



Now, to make those arrows (or any other furniture) into teleports, we have to assign the "teleport" action and its parameters to it. So, in the library it will look like this:


 <actions>
 <a name="teleport" destRoom="Dance Club" destTile="9,42" />
 </actions>


Now, this method is not flexible enough - this furniture object, when placed on any map will always work as a teleport, and with the same parameters (like destRoom="Dance Club"). This limits its usability to just specific cases.

2. This limitation can be overcome by assigning the action directly in the map XML code. This way we can use one furniture or tile object for different actions, or with different action parameters. For example, the same arrow object can be used to point to different maps (as on the Levee map in Theo Chat v2):

<f col="4" row="4" libID="2" libItemID="66" libFrame="8">
 <actions>
 <a destRoom="Apartment" destTile="7,14" name="teleport" />
 </actions>
</f>

<f col="17" row="10" libID="2" libItemID="66">
 <actions>
 <a destRoom="Dance Club" destTile="9,42" name="teleport" />
 </actions>
</f>

This action details (what is actually does) are defined in the World.placeCharacter - this is a function that places the main character on a specific tile on the map.

If you don't want the character to be able to step on the teleport, just use walkable="0" in the map XML (or remove walkable="1" from the library XML), but in this case you have to set selectable="1", otherwise the character will never get to that tile/furniture. When selectable="1", it will make that object mouse-clickable, so you will be able to direct the character to it. The chair works this way - it has the "sit" action assigned to it, that makes the character sit when he/she reaches it, but it also has walkable="0" so the character can not step/walk on the chair, and the selectable="1" so we can click on the chair to make the character walk to it.

3. Characters

Characters graphics are stored in separate SWF files with a strictly defined structure. This SDK comes with two characters - woman.swf and man.swf. The sources of these files are located in "/library/fla/".

Character map object

The characters SWF files contain all the character animations. The ones that come with TWB contain the walking animation in all 8 directions, plus the dancing animation and the sitting pose. For all those animations the clothes/accessories animation layers are also included. The frame labels are important and are used to organize all the frames. Study the FLAs that come with this SDK in case you want to create your own characters.

3.1 Characters actions (animations)

The character library file has a more complex structure, since it contains also information about character actions (animation). Here is an example (fragment):

<?xml version="1.0"?>



<library id="3">
 <items>
 
 

 
 <actions>
 <a name="default_walk" frames="5" nonStop="1" movable="1"/>
 <a name="dance" frames="8" nonStop="1" allowedActionDirs="5"/>
 <a name="sit" snapToAction="1" allowedActionDirs="4,6"/>
 </actions>
 

 
 <actions>
 <a name="default_walk" frames="5" nonStop="1" movable="1"/>
 <a name="dance" frames="8" nonStop="1" allowedActionDirs="5"/>
 <a name="sit" snapToAction="1" allowedActionDirs="4,6"/>
 </actions>
 
 ....

Each block represents one character. The code in bold describes the man.swf character and all the animations it contains.

The first line defines the main attributes and the location of the SWF, similar to furniture library:

Here are the parameters used:

id, url, -those work the same as for floor tiles and furniture
speed - the character animation speed. It's actually the delay between the frames when animating them, so a higher number will decrease the animation speed (so it will take a character longer to get from one tile to another).

The next block <actions> lists all the animations the character contains - each action in it's <a> block. Example:

<a name="default_walk" frames="5" nonStop="1" movable="1"/>

The list of allowed attributes are:

name - an unique name animation name
frames - the length of the animation in frames (1 by default)
nonStop - a flag that defines if the animation is looping forever or stops after one loop (0 by default)
movable - a flag that defines if the animation is of the character moving (ex: walking, running, jumping, etc.) or not (ex: standing in a pose, dancing, etc). (0 by default)
snapToAction - a flag that defines if, when stepping on a new tile, the character walks (or does another type of moving animation) to the center of the tile and then starts this animation, or it just "snaps" into the new animation (0 by default).
Example: When using a "sitting on a chair" pose, you will need to use snapToAction=1, since you don't want the character to walk into the chair object and then sit on it, you want the sitting to happen as soon as the character gets to the tile (to the chair on that tile).
useLeftRighSteps - this is a flag that applies just to movable animations and it defines if it's a symmetric one - uses the right-left steps (1 by default).
Most of the characters that move around have the moving animation made of a "left step, right step" animation loop (otherwise they would always step just with one foot forward). This divides the animation in two symmetric parts. When turning this flag on, the character uses just one half of animation per tile (so on the first tile it will step on with the left foot, and on the next one - with the right foot). If this flag is turned off, the both left and right steps will happen within one tile. Depending on the animations you may want to turn on or off this flag (when steps are too large or two short). Also, for nonsymmetrical animations (ex: jumping forward with both feet) you will need to turn this flag off.
allowedActionDirs - this is a flag that defines in what directions an animation is available. In most of the cases you will have animations allowed in all 8 directions, like walking (and this is the default case). But, sometimes, you don't need all the directions.
Example: In this SDK the sitting animation/pose is defined just in two directions for each character and the dancing is allowed just in one direction - down, facing the "camera" (in this case we will have allowedActionDirs=5).

All the animation defined in the character's library XML file have to be present in the character SWF file, with the frames marked correspondingly: animation name + underscore + direction name. For example, for the default_walk animation, that has animations in all 8 directions, we will have the frames named: default_walk_down, default_walk_down_left, default_walk_left, default_walk_up_left, default_walk_up, default_walk_up_right, default_walk_right and default_walk_down_right.

3.2 Characters layers (clothes and accessories)

You can add layers to the characters, if you plan to modify them in any way - like clothes and accessories (sunglasses, etc). In order to do that you need to define the actions in the character XML library and also to have to corresponding graphics layers inside the character's SWF.

Here is how the actions are defined in the character's XML description:

<items>
 
 <actions>
 <a name="default_walk" frames="5" nonStop="1" movable="1"/>
 <a name="dance" frames="8" nonStop="1" allowedActionDirs="5"/>
 <a name="sit" snapToAction="1" allowedActionDirs="4,6"/>
 </actions>
 <layers>
 <group name="hair">
 <layer name="hair1"/>
 <layer name="hair2"/>
 <layer name="hair3"/>
 <layer name="hair4"/>
 <layer name="hair5"/>
 </group>
 <group name="accessories">
 <layer name="accessory1"/>
 </group>
 <group name="clothes">
 <group name="jackets">
 <layer name="jacket1"/>
 </group>
 <group name="tops" required="1">
 <layer name="top2"/>
 <layer name="top1"/>
 </group>
 <group name="bottoms" required="1">
 <layer name="bottom2"/>
 <layer name="bottom1"/>
 </group>
 </group>
 
 </layers>

</items>

You have to declare the layers in the XML only if you want to control then in any way (show and hide). Otherwise you can just skip them (like the character body, if it never changes and is never hidden).

The simplest layer looks like:

<layers>
<layer name="accessory1"/>
</layers>

Note that you can group layers in groups (like all the T-shirts) to interchange them (change character's t-shirt, while having just one on at a time). Sub-groups are also supported.

Note that in the character's SWF all the clothes layers are on the same timeline, as separate layers, but without any nesting/grouping. This is why the layer name in the XML should be unique: <layer name="accessory1"/>.

There is an additional parameter for groups - "required" - used like this:

<group name="bottoms" required="1"><layer name="bottom1"/></group>

When required=1, it means that this group of layers is mandatory and the character should wear one of the layers from this group. This way you can ensure that your character always has the pants on, for example.

All the layers declared in the XML should have the corresponding layers in the timeline, with the movieclips on them containing that layers graphics and named (the movieclips) exactly the same (as the layer names in the XML). For the code above, there should be a movieclip called "bottom1", for example.

4. The Catalog

The Catalog is an XML file (catalogue.xml in the main folder) that stores the references to all the libraries, all the available backgrounds and foregrounds and also the list of the available maps (in case you want to have access to them in Map Editor - for re-editing). The catalog.xml is used by the Map Editor in order to be able to reference all this information. When the Map Editor generates a map, it includes all the needed references to the libraries and backgrounds/foregrounds automatically.

This is how catalog.xml looks like:

<?xml version="1.0"?>


<maps>
 <map url="maps/theolabs08_1.xml"/>
 <map url="maps/ground.xml"/>
 <map url="maps/chat_levee.xml"/>
 <map url="maps/chat_dance_club.xml"/>
 <map url="maps/chat_apartment.xml"/>
 <map url="maps/theolabs07.xml"/>
 <map url="maps/theolabs08.xml"/>
</maps>
<library>
 <floor>
 <lib url="library/floor.xml"/>
 </floor>
 <furniture>
 <lib url="library/furniture.xml"/>
 <lib url="library/theochat_furniture.xml"/>
 </furniture>
 <characters>
 <lib url="library/characters.xml"/>
 </characters>
 </library>
<backgrounds>
 
 
 
 
</backgrounds>
<foregrounds>
 <f url="maps/atrium/disco_fg.gif"/>
 <f url="maps/atrium/river_fg.png"/>
 <f url="maps/atrium/room_fg.png"/>
</foregrounds>

Last updated: September 16, 2009