monsters.xml [Mana Documentation]

- monsters.xml file configuration

monsters.xml file configuration

Data from the monsters.xml file are used to set up configuration values about every computered related beings the players will encounter during the online experience.

The monsters.xml file has to be located in the data directory.

Each configuration option in this xml file, is defined using a <monster> tag within the <monsters> main node, which itself has got an <attributes> child node, and some others. Here is an example:

monsters.xml sample

 <?xml version="1.0"?>
 <monsters>
    <monster id="0" name="Maggot" targetCursor="small">
      <attributes
        hp="20"
        size="4"
        speed="2.0"
        attack-min="10"
        attack-delta="2"
        attack-magic="0"
        hit="10"
        evade="5"
        physical-defence="5"
        magical-defence="0"
        mutation="50"
      />
      <exp>10</exp>
    </monster>
 </monsters>

Note: This file can be used by both the client and the server if the necessary data is provided. That's why we provide options for both applications here for simplification and easier documentation purpose. But when you should be careful to provide only the client data when dealing with client configuration, or the players will more information about the monsters than they should actually have.

General (Client and server) nodes description

<monsters> node description

The <monsters> node is the monsters.xml file main node and permits to determine monsters definition start and ending. This node has only one parameter for now, offset, which is added to all the monster IDs. It defaults to 1002 for the TmwAthena protocol, for backwards compatibility with older clients, which did it automatically in the netcode.

This node is required by both the client and the server.

monsters node sample

 <?xml version="1.0"?>
 <monsters>
 ...
 </monsters>

<monster> node description

The <monster> node is used to define the different values used to bring a specific monster up to life within the game. Each monster's definition is then defined within its start and ending tags.

This node is required by both the client and the server.

monster node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
id	integer	Yes		It is the id of the monster. This parameter has to be unique for each monster. The system will use the monster id to refer on it in many ways.
name	string	No	“unnamed”	Tells the monster name. Used to ease configuration on server and with the client but displayed to players on the client side.
targetCursor	string defined value	No	“normal”	Used by the client only. Tells which circle cursor size should be use when displaying the target cursor around the monster sprite while in game. It mainly depends on the sprite's pixel size. Acceptable values are: small normal large

<attack> node description

The <attack> node is used to define how to compute each possible monsters attacks, for both the client and the server.

This node is optional by both the client and the server.

attack node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
    <attack
     id="1"
     priority="1"
     type="physical"
     pre-delay="10"
     aft-delay="5"
     damage-factor="1"
     range="32"
     animation="attack"
     script-function="strike"
     particle-effect="graphics/particles/attack.particle.xml"
    />
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
id	integer	Yes		Id number of the attack (unique for each monster) used to identify the monster type in the netcode.
priority	integer	No	1	How likely the monster is to choose this attack when it got multiple attacks it can use in the current situation.
type	string defined values	Yes		Attack type. can be `physical`, `magical` (or `magic`), or `other` (Hazard damages not based on the victim's defence.
pre-delay	integer	Yes for the server No for the client		Delay in game ticks¹⁾ between the decision to perform this attack and performing it.
aft-delay	integer	Yes for the server No for the client		Delay in game ticks after the attack until the monster can act again.
damage-factor	integer	Yes for the server No for the client		Multiplier applied to minimum and maximum damage as they have been calculated by using the monster attributes.
range	integer	Yes for the server No for the client		Range of the attack, in tiles.
animation	string defined values	No for the server Recommended for the client		Animation that is played when the monster uses this attack. The value must correspond to an animation defined in the monster.xml sprite file.
script-function	string	No	””	Defines the script function name to be used, if a valid script file if provided by the `<script>` node. The function must also exist within the file, of course.
particle-effect	filename	No	””	Defines the xml relative or absolute filename to be used for displaying a particle effect when this attack is used. The given filename must be relative to the data/ folder.

Server nodes description

<attributes> node description

The <attributes> node is used to define the current monster main necessary attributes. These shouldn't be left in the client version.

This node is required by the server, and will be ignored by the client.

attributes node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <attributes
      hp="10"
      attack-min="5"
      hit="10"
      evade="5"
      physical-defence="5"
      ...
     />
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
hp	integer	Yes		The monster hit points.
size	integer	No	16	The monster maximal amplitude in pixels. Used to compute player's hit area.
speed	float	No	4.0	The monster's speed in tiles per second. (A tile is the smallest square map unit: by default, a tile is 32 pixel long.)
attack-min	integer	Yes		The minimal attack strength of the monster. If your character hasn't got any armor, these are the minimal hit points he/she will lose when hit by the monster.
attack-delta	integer	Yes		The amplitude between minimal and maximal damages the monster can do.
attack-magic	integer	Yes
mutation	integer	No	0	The mutation indicates the amplitude in percent where attributes get modified with. For instance, with a mutation of 50, each attribute can be altered to become 100% to 149% of what they are. A value < 0 or > 99 will be ignored.

<behavior> node description

The <behavior> node is used to define the monster's way to move and think when dealing with players interaction. These values shouldn't be left in the client version.

This node is required by the server, and will be ignored by the client.

behavior node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <behavior
      aggressive="false"
      cowardly="false"
      track-range="5"
      stroll-range="2"
      attack-distance="32"
     />
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
aggressive	boolean true/false	Yes		Defines if the given monster will attack the player as soon as it see them. If set to “false”, the monster only starts to attack its opponent once it received the first damages.
cowardly	boolean true/false	Yes		Defines if the monster will start to flee the battle once its HP are becoming low. Note: : Not implemented yet.
track-range	integer	Yes		Distance in tiles the monster tracks enemies in (pathfinding algorithmn is used for calculating distance).
stroll-range	integer	Yes		Distance in tiles the being chooses new destinations in when not fighting (as when wandering).
attack-distance	integer	Yes		Preferred distance in pixels to the enemy the monster tries to reach when in combat (horizontal or vertical). Used for range attackers, for instance. A value of 32 means a close combat range when your tiles side length are 32 pixels wide.
script	file name	No	””	Filename of a script that controls the monsters behavior. Should only be used for rare monsters to reduce server load. (Providing this file makes all the other tags unnecessary). The script filename must be relative to the `data/scripts` directory.

<exp> node description

The <exp> node is used to define the reward points for defeating a monster. See the Skill system documentation for further details. These values shouldn't be left in the client version.

This node is optional but recommended for the server, and will be ignored by the client.

exp node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <exp>150</exp>
   ...
   </monster>
 ...
 </monsters>

Type	Mandatory	Default value	Description
integer	No	0	Tells how much experience points a monster is giving upon victory.

<drop> node description

The <drop> node is used to define items dropped after defeating a monster. See the items.xml documentation for further details. There can be multiple <drop> nodes for one monster. These values shouldn't be left in the client version.

This node is optional but recommended for the server, and will be ignored by the client.

drop node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <drop item="522" percent="0.1" />
     <drop item="501" percent="15.0" />
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
item	integer	Yes		Tells the drop item Id taken into your items.xml file.
percent	float	Yes		Tells the chance (8.0 = 8%) to see the drop be spanwed on the map floor after the monster's death.

<script> node description

The <script> node is used to define the monster through a whole script.

This node is optional for the server, and will be ignored by the client.

script node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <script>mymonster.lua</script>
   ...
   </monster>
 ...
 </monsters>

Type	Mandatory	Default value	Description
string filename	Yes		The script filename to be used for the given monster. The script filename must be relative to the `data/scripts` directory.

<vulnerability> node description

Note: FIXME : Not implemented yet.

The <vulnerability> node is used to define the current monster vulnerabilities, or on the opposite strength against one or several magical elements. These values shouldn't be left in the client version.

This node is optional for the server, and will be ignored by the client.

vulnerability node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <vulnerability element="fire" factor="1.5" />
     <vulnerability element="earth" factor="0.7" />
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
element	string	Yes	””	Tells to which element the weakness or the strength is. ('fire', 'earth', 'ice', 'metal' are some examples.)
factor	float	Yes	””	Tells how much the monster defence against an element is reduced by, in percent. A value of 0.7 indicates that the defence is lowered by 30%. On the contrary, a value > 1.0 indicates that de defence is higher again the given element.

Client nodes description

<sprite> node description

The <sprite> node is used to define the monster sprite used to be displayed by the client.

This node is unused by the server, optional but very recommended for the client.

sprite node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <sprite>monsters/my-monster.xml</sprite>
   ...
   </monster>
 ...
 </monsters>

Type	Mandatory	Default value	Description
xml filename	Yes	””	Tells the xml file used to display the monster sprites. (Used by the Mana Client only). The given file must be relative to the `data/graphics/sprites` directory.

<sound> node description

The <sound> nodes are used to define the monster sounds played on certain monster's events.

This node is unused by the server, and optional for the client.

sound node sample

 <?xml version="1.0"?>
 <monsters>
   <monster id="1" name="Monster Name">
     <sound event="hit">monsters/maggot/maggot-hit1.ogg</sound>
     <sound event="hit">monsters/maggot/maggot-hit2.ogg</sound>
     <sound event="miss">monsters/maggot/maggot-miss1.ogg</sound>
   ...
   </monster>
 ...
 </monsters>

Parameter name	Type	Mandatory	Default value	Description
event	string defined keywords	Yes		Tells the event at which the corresponding sound should be played. Available events are: 'die', 'miss', 'hit', 'strike', 'dodge'. There can be several sounds nodes and so, events for one monster. The same event can even be set multiple times. The given sounds are played randomly in this case.

¹⁾ 10 game ticks = 1 second.