===== 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 ''<monster**s**>'' main node, which itself has got an ''<attributes>'' child node, and some others.
Here is an example:

<file xml 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>
</file>

**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.

<file xml monsters node sample>
 <?xml version="1.0"?>
 <monsters>
 ...
 </monsters>
</file>



=== <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.

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

^ 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.

<file xml 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"
     effect-id="11"
    />
   ...
   </monster>
 ...
 </monsters>
</file>

^ 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((10 game ticks = 1 second.)) 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.  |
| action      |  string \\ defined values  |  No for the server \\ Recommended for the client  |  "attack"  | Animation name 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.  |
| missile-particle  |  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. The missile particle will be displayed from the attacker to the victim. Used for arrows for instance.  |
| <del>particle-effect</del>((deprecated.))  |  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. Usable until the 0.5.2 version. See the ''effect-id'' parameter for the versions >= 0.6.  |
| effect-id  |  integer  |  No  |  -1  | Defines the effect id triggered on the monster when it is attacking the player. Usable on versions >= 0.6.  |
| hit-effect-id  |  integer  |  No  |  -1  | Defines the effect id triggered on the victim when the monster is performing a regular hit. Usable on versions >= 0.6.  |
| critical-hit-effect-id  |  integer  |  No  |  -1  | Defines the effect id triggered on the victim when the monster is performing a critical hit. Usable on versions >= 0.6.  |

==== 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.

<file xml 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>
</file>

^ 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  | | The magical attacks are removing hp when hit but are computed against magical defence instead.
| 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. |
| gender | string | No | unspecified | The gender of the monster. Valid values are: "male", "female", "unspecified". This information has no effect on the behaviour of the being. But if a gender is set the client can display this gender. |


=== <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.

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

^ 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:** FIXME: 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 pixels 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 [[manaserv_statistics_system#experience and skills|experience]] 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.

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

^ 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.

<file xml 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>
</file>

^ 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.

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

^ 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.

<file xml 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>
</file>

^ 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.

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

^ 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.

<file xml 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>
</file>

^ 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.   |