Navigation

How to specify animations

One of the most important components of the game data are animations, i.e. sequences of images that the sprites (e.g. the passenger) cycle through. At some places, you will only want a single (static) image instead of an animation, but most of the time, this is still an animation, internally.

Creating an animation involves two major steps. First of course you'll have to create the single images (frames) that are to be displayed one after another. I can't help you much with this step, but you need to take care of the following aspects: a) You will generally want the animations to have some transparent regions (otherwise all sprites would always cover a rectangular space), and therefore you'll have to save the frames in a file-format that supports transparency - PNG is most likely the best choice. b) The frames have to be saved individually as name0000.png, name0001.png, name0002.png and so on in the correct order. Be sure to place these files under images or a subdirectory below images (see section on filenames).

The second step is telling TaxiPilot all it needs to know about these animations, including the options to be used during playback. This step will be described in detail, here. Let's first have a look at the basic syntax to be used:

  <tagname file_pattern="path_to_animation/name_of_animation_%1.png" frames="4" />

First note, that of course you won't write "tagname" in your configuration-files, but rather use the appropriate tagname needed to identify, what exactly the animation is to be used for. Which name to use will be detailed in the appropriate sections of this document. The next two parameters, however will be the same for all animations, you use:

The "file_pattern"-attribute takes as parameter the filename-pattern of your animation. Note that the "%1" in the pattern will be replaced with 0000, 0001, ..., to read the first, second, ... frame of the animation (see the paragraph above on how to name the files of your animation). As an exception, if an animation only consists of a single frame (i.e. is a static image), you can directly specify the filename of that frame (without the "%1").

The "frames"-attribute is used to specify the number of frames in the animation. Like the above parameter, the "frames"-attribute may not be omitted.

One further parameter which always be used, but is not mandatory: "anim_frame_period" may be set to an integer number of milliseconds that each frame of this animation will be shown. E.g. if you specify

  <tagname file_pattern="name_of_animation_%1.png" frames="4" anim_frame_rate="200" />

that means, that the animation will be played at 5 frames per second (this does not influence the rate at which the sprite is moved, only the rate at which its image changes). If changes from frame to frame are small, you can set this parameter relatively high, and still get a smooth animation (with less drawing).

Finally you can always use the attribute alpha:

  <tagname file_pattern="name_of_animation_%1.png" alpha="true" frames="4" />

The meaning behind this parameter is this: Usually TaxiPilot will strip any alpha-channel it finds off the graphics. This is done for performance reasons and most of the time, you really don't need true alpha-blending. In those place where you do need true alpha-blending (for instance if you want to create a moving semi-translucent cloud), you'll have to explicitely specify 'alpha="true"' for that animation. Keep in mind, that alpha-blending really is a performance hog on slow machines. So try to keep objects with alpha-blending small.

Additionally, there is a number of parameters influencing animations, that can only be used in some places (refered to in those sections as "additional parameters"):

"anim_oscillating" is a boolean attribute, that specifies, whether the animation is simply to be played from first frame to last frame (anim_oscillating="false"), or whether it is to be played from first frame to last frame, and then played reverse back to the first frame (anim_oscillating="true"). This option is available in most places, except for animations for teleporting.

"anim_continuous" is a boolean attribute, that specifies, whether an animation is to be repeated over and over again. This is only possible for some few animations, and for some further, it is the only possible setting. As an example, the animation of a passenger walking, is always continuous, since it can not be predetermined, how far the passenger will have to walk. For moving objects however, you may freely chose, whether the animation will be played continuously or only once.

"repetitions" is a lot like the above attribute, but takes an integer number of times that this animation will be played. E.g. it may be used for animating a waving passenger. If the passenger is to wave five times, instead of saving each frame five times, you can specify repetitions="5" and only need each frame once. This option is available in more places than the above, but naturally can not be used in conjunction with anim_continuous="yes".

Wherever you can configure an animation, you may also fill in a (static) text instead. Most of the time, this does not make a lot of sense, but if, e.g. you want to move a text-message through the screen, you'd probably use such a text instead of creating an image containing that text. This way, you make life a lot easier to potential translators, and also save a few bytes on your harddisk. Creating such a text works as follows:

  <tagname text="Sorry, this is it,\nthis is the last level!" align="left" valign="top" font="helvetica"
    r="10" g="255" b="150" max_width="300" max_height="50" break="true" smooth="true" align_handle="true"
	text_period="500"/>

First of all, note, that once again "tagname" only stands for whatever tag-name is appropriate for this place in the config (same as for the other animations). The first parameter should be relatively obvious. "text" is a takes as value the string that is to be displayed. If you insert a '\n' inside this text, this will be interpreted as a (forced) line break. Automatic breaking/wrapping of lines can be achieved by setting the "break"-parameter to true (by default lines do not get wrapped).

You may specify horizontal and vertical alignment using "align" and "valign". Possible values for these attributes are "left", "center", "right" and "top", "center", "bottom", respectively. Note that the vertical alignment-parameter will generally not have any effect if "align_handle" is set to false (see explanations for "align_handle" below).

The "font"-attribute specifies the name of the font to be used (please keep in mind, that non-standard fonts might not be available on the player's computer), the color of the text to be displayed is given in RGB color-scheme using the integer parameters "r", "g", and "b".

Next thing to explain is the size-parameters. Unlike you might have expected, the font-size is not given as point-size, but rather as maximum width ("max_width") and height ("max_height") in pixels of the rendered string. The reason is that the same point-size may result in greatly differing actual sizes of the text on different systems, that e.g. use different font-resolutions. Using "max_width" and "max_height" then, you specify a rectangular region that limits the text. TaxiPilot will always try to use a font-size as large as possible, but will never exceed the given boundaries.

That said, the "smooth"-attribute may affect, whether TaxiPilot will try to come as close to the given boundaries as possible, or whether it will limit itself to point-sizes that can be displayed smoothly. The results of this parameter are not quite predictible. There are systems, that will by themselves refuse to scale fonts that are not available in a given point-size (i.e. will only ever use "smooth" fonts) and there may be systems that are able to scale fonts smoothly. Either way, if you're mostly concerned about getting the text to display smoothly, you should set smooth="true". If however, you're most concerned about the exact region covered by the text, use smooth="false".

Last but not least, the "align_handle"-attribute specifies, whether the coordinates given for the text (esp. in the context of moving objects) are interpreted as the top-left corner of the rectangle containing the text (like it would be the case for any regular graphics-file), or whether the "handle" is placed according to the alignment-parameters. E.g. with align="center" valign="bottom" align_handle="true", the "handle" would be places on the bottom center of the text. Experimentation may help understand what I'm trying to explain.

The "text_period"-attribute specifies, after what time the animation will be considered "complete". Most of the time, this parameter does not have any effect, it only makes sense for such animations, where something happens when the animation is over, such as teleporting-animations. Again: Most of the time you can forget about this parameter.

Last modified: Apr 03 2005 17:50 (GMT)