Sprite System

The animation system and its related files is the most wide spread engine system working throughout the client. Animation files can indeed be used for animating the characters, the monsters, the maps tiles, the emoticons, and so on...

This chapter will the attempt to provide documentation about sprite files within the mana client. If you want to create particle effects, see the particle system documentation.

XML Sprite files

Most of the time, an animation parameter (in npcs.xml, in items.xml or monsters.xml for instance) is linking to an XML file where the actual animation to play for each action is described.

Here are example of sprite files and how to configure them:

Note on the playersets configuration

The playersets animations, corresponding to male and female animations for each races, are currently declared in the items.xml file.

Note on the playersets definition

Note: The races declaration should be moved to the races.xml file, and support for more than one race is to be added.
QUESTION: Will we allow to have a custom different genders value as it is theoretically possible in the server?

You can find below a working example about how to set up the link to playersets animation files for each available gender:

Note: Currently, only the id -100 for the first race is allowed, and only one race is allowed in the client anyway.

<?xml version="1.0"?>
<items>
  <!-- ... -->
  <item id="-100" type="racesprite" name="Human">
    <sprite gender="male">player_male_base.xml</sprite>
    <sprite gender="female">player_female_base.xml</sprite>
  </item>
  <!-- ... -->
</items>

For each XML file declared above, a corresponding file in graphics/sprites((per default, see paths.xml to change the default paths.)) will have to exist.

Note on the hair sets definition

Note: The hairs declaration should be moved to the races.xml file, as hairsets should be linked to the playerset, and thus, the race.
QUESTION: Will we allow to have a custom different genders value for hairs?

You can find below a working example about how to set up the link to hairsets animation files for both server, as TmwAthena has a limitation on the permitted Id:

    <item id="-1" type="hairsprite" name="Flat ponytail">
        <sprite>hairstyle1.xml</sprite>
    </item>
    <item id="-2" type="hairsprite" name="Bowl cut">
        <sprite>hairstyle2.xml</sprite>
    </item>
    <item id="-3" type="hairsprite" name="Combed back">
        <sprite>hairstyle3.xml</sprite>
    </item>
    <item id="-4" type="hairsprite" name="Emo">
        <sprite>hairstyle4.xml</sprite>
    </item>
    <item id="-5" type="hairsprite" name="Mohawk">
        <sprite>hairstyle5.xml</sprite>
    </item>
    <item id="-6" type="hairsprite" name="Pompadour">
        <sprite>hairstyle6.xml</sprite>
    </item>
    <item id="-7" type="hairsprite" name="Center parting/Short and slick">
        <sprite>hairstyle7.xml</sprite>
    </item>
    <item id="-8" type="hairsprite" name="Long and slick">
        <sprite>hairstyle8.xml</sprite>
    </item>
    <item id="-9" type="hairsprite" name="Short and curly">
        <sprite>hairstyle9.xml</sprite>
    </item>
    <item id="-10" type="hairsprite" name="Pigtails">
        <sprite>hairstyle10.xml</sprite>
    </item>
    <item id="-11" type="hairsprite" name="Long and curly">
        <sprite>hairstyle11.xml</sprite>
    </item>
    <item id="-12" type="hairsprite" name="Parted">
        <sprite>hairstyle12.xml</sprite>
    </item>
    <item id="-13" type="hairsprite" name="Perky ponytail">
        <sprite>hairstyle13.xml</sprite>
    </item>
    <item id="-14" type="hairsprite" name="Wave">
        <sprite>hairstyle14.xml</sprite>
    </item>
    <item id="-15" type="hairsprite" name="Mane">
        <sprite>hairstyle15.xml</sprite>
    </item>
    <item id="-16" type="hairsprite" name="Bun">
        <sprite>hairstyle16.xml</sprite>
    </item>

For each XML file declared above, a corresponding file in graphics/sprites((per default, see paths.xml to change the default paths.)) will have to exist.

Configuration of a sprite file

Here is an example of a playerset XML file:

Note: You can also consider that NPCs, monsters, equipment sprites, and so on, can be configured the same way than below.

<?xml version="1.0"?>
<sprite name="player" action="stand">
  <imageset name="base" src="graphics/sprites/player_male_base.png"
            width="64" height="64" />

  <action name="stand" imageset="base">
    <animation direction="down">
      <frame index="0" />
    </animation>
    <animation direction="left">
      <frame index="18" />
    </animation>
    <animation direction="up">
      <frame index="36" />
    </animation>
    <animation direction="right">
      <frame index="54" />
    </animation>
  </action>
  <!-- ... -->
  <action name="attack_bow" imageset="base">
    <animation direction="down">
      <sequence start="13" end="17" delay="75" />
      <end />
    </animation>
    <animation direction="left">
      <sequence start="31" end="32" delay="75" />
      <sequence start="33" end="35" delay="90" />
      <end />
    </animation>
    <animation direction="up">
      <sequence start="49" end="53" delay="75" />
      <end />
    </animation>
    <animation direction="right">
      <sequence start="67" end="71" delay="75" />
      <end />
    </animation>
  </action>

</sprite>

Here is a description of each available nodes and their parameters:

`sprite` node
Parameter	Value Type	Required	Default Value	Description
name	string	no	""	The sprite name. Only used for self-documentation. FIXME: Can we remove that? Or will it be used later?
action	string	yes	""	The default action name used when the system doesn't find the requested one for the given animation.
`imageset` node (childnode of `sprite`)
There can be several `imageset` childnodes, as long as they have different `name` values.
Parameter	Value Type	Required	Default Value	Description
name	string	yes	-	The imageset internal name. This name is used as a reference later in an `animation` node. Must be unique.
src	string	yes	-	The file path of a PNG file used when invoking the imageset. The file path must be relative to the `data/` folder.
width	integer	yes	-	The sprites' width used when tiling the PNG file to obtain the animation frames. See notes about that below.
height	integer	yes	-	The sprites' height used when tiling the PNG file to obtain the animation frames. See notes about that below.
offsetX	integet	no	0	The image horizontal (from left to right) offset to used when displaying the frames. Can be negative.
offsetY	integer	no	0	The image vertical (from top to bottom) offset to used when displaying the frames. Can be negative.
`action` node (childnode of `sprite`)
There can be several `action` childnodes, as long as they have different `name` values.
Parameter	Value Type	Required	Default Value	Description
name	string Defined values: ("default", "stand", "walk", "sit", "dead", attack")	yes	-	The action name. The core actions (walk, sit, ...) must be defined using the predefined values described in the 'Value type' column. Attack actions are freely named using the `attack-action` parameter in the [items.xml](items.xml.md) and thus, have to be named accordingly. Only the default "attack" action has to be specifically set. E.g.: If the "attack_bow" action name value is corresponding to the `attack-action` parameter value in [items.xml](items.xml.md) for a bow. Then, this action will be used when using this weapon instead of the default "attack" action. Also, the "default" action will be played when the default given in the sprite action parameter isn't found.
imageset	string	yes	-	The imageset reference name. It must correspond to one of the imageset name values.
`animation` node (childnode of `action`)
There can be several `animation` childnodes, as long as they have different `direction` values.
Parameter	Value Type	Required	Default Value	Description
direction	string Defined values: ("up", "down", "left", "right")	yes	-	The animation direction. Its value must be unique per animation node. Also, the first animation declared is the default one when the requested direction isn't found.
`frame` node (childnode of `animation`)
There can be several `frame` childnodes within an `animation` node, even mixed with `sequence` ones, but the animation will stop loading once it has reached an `end` childnode.
index	integer	yes	-	The frame index to display. When the imageset file is loaded, it is tiled into pieces of the size given in its `imageset` node, from left ot right, and from top to the bottom of the PNG file. The index is representing the tile number to display. Note that the first tile index value (representing top-left part of the image) is 0.
delay	integer	no	75	The time the frame is displayed in milliseconds. Must be positive.
offsetX	integer	no	0	The image horizontal (from left to right) offset to used when displaying the frames. Can be negative.
offsetY	integer	no	0	The image vertical (from top to bottom) offset to used when displaying it. Can be negative.
`sequence` node (childnode of `animation`)
There can be several `sequence` childnodes within an `animation` node, even mixed with `frame` ones, but the animation will stop loading once it has reached an `end` childnode.
start	integer	yes	-	The first frame index to display. See index parameter of the `frame` node.
end	integer	yes	-	The last frame index to display. Note that every frames with indexes between start and end parameter values will be played.
delay	integer	no	75	The time the frames are displayed in milliseconds. Must be positive.
offsetX	integer	no	0	The image horizontal (from left to right) offset to used when displaying the frames. Can be negative.
offsetY	integer	no	0	The image vertical (from top to bottom) offset to used when displaying the frames. Can be negative.
`end` node (childnode of `animation`)
An `end` childnode set the end of the current animation. It doesn't have any parameters. This node is optional.

XML inclusion support

Another XML sprite file can be included by using the <include> tag.

For instance, if you want to override the images, you'll need to specify them before the include element. If you want to override any animations, you have to do so after the include element. Example:

<sprite>
 <imageset name="base" />
 <!-- ... -->
 <include file="other-sprite-file.xml"/>
 <!-- possibly override or introduce new actions -->
</sprite>