Data from the items.xml file are used to set up configuration values about every items the players will be able to carry during his/her online experience.

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

Each configuration option in this xml file, is defined using a <item> tag within the <items> main node. Here is an example:

items.xml sample

 <?xml version="1.0"?>
 <items>
   <item id="501" name="Cactus Drink"
    image="use-potion-a.png|G:#22ff22"
    description="A fresh drink."
    effect="+15 HP"
    type="usable"
    hp="15"
    weight="4"
    max-per-slot="10"/>
    ...
 </items>

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 have more information about the items than they should.

Used only by the server to handle inventory limitations.

Parameter name	Type	Mandatory	Default value	Description
max-per-slot	integer	No	1	Indicates the maximum of a given item the character can stack in the same inventory slot. Note that items with equip/unequip effect become equippable. I.e: Tey have a max-per-slot parameter set to 1 whatever the current parameter tells.
sprite_id	integer	No	0	The item ID sent by the server when another character is wearing the item. This can be used to avoid revealing the real item type when you have look-alike items with different properties.
value	integer	No	0	Tells how much does the item cost with the default currency. See units.xml for more details about how to set up the World currency (and weight) name. : This doesn't handle multiple currencies and will be removed once a new way to define that has been added.
range	integer	No	0	Only taken in account if the item is a 1handed or 2handed typed weapon. (See the type parameter.) : Set the weapon range in pixels, again.
script	string LUA Script file	No	””	WARNING: Deprecated! Manaserv v0 only: Tells the script file to be run when the item is used. The filename must be relative to the data/script/ folder.
element	integer (defined values)	No	0	WARNING: This has never worked, and will be replaced with autoattack system. Only taken in account if the item is a 1handed or 2handed typed weapon. (See the type parameter.) Set the weapon element. Available elements are: - Fire - ……
attack-min	integer	No	0	WARNING: Deprecated! Manaserv v0 only: Set the minimum HP damage value dealt with this item. (Without counting either the weapon skill or the character strength.)
attack-delta	integer	No	0	WARNING: Deprecated! Manaserv v0 only: Set the HP damage value range dealt with this item. Damages: min ↔ min+delta
lifetime	integer	No	0	WARNING: Deprecated! Manaserv v0 only: Tells in tenth of a second the time in which the modifier values below are applied (if set) to the character's attributes when using the given item.
strength	integer	No	0	WARNING: Deprecated! Manaserv v0 only: When the given item is used, the character's strength is modified by adding this value which can be negative. The effect will be lasting for the lifetime value in seconds / 10.
agility	integer	No	0	WARNING: Deprecated! Manaserv v0 only: When the given item is used, the character's agility is modified by adding this value which can be negative. The effect will be lasting for the lifetime value in seconds / 10.
vitality	integer	No	0	WARNING: Deprecated! Manaserv v0 only: When the given item is used, the character's vitality is modified by adding this value which can be negative. The effect will be lasting for the lifetime value in seconds / 10.
willpower	integer	No	0	WARNING: Deprecated! Manaserv v0 only: When the given item is used, the character's willpower is modified by adding this value which can be negative. The effect will be lasting for the lifetime value in seconds / 10.
intelligence	integer	No	0	WARNING: Deprecated! Manaserv v0 only: When the given item is used, the character's intelligence is modified by adding this value which can be negative. The effect will be lasting for the lifetime value in seconds / 10.
dexterity	integer	No	0	WARNING: Deprecated! Manaserv v0 only: When the given item is used, the character's dexterity is modified by adding this value which can be negative. The effect will be lasting for the lifetime value in seconds / 10.

The Mana server isn't concerned by the given parameters and will ignore them.

These “items” are purely virtual ones. They are used to configure the available hairstyle, races, and weapon type within an TmwAthena session. The client use them to get in sync with server when dealing with such information.

Note: : The ManaServ client is using this hairstyle system for now. This should be fixed by adding the available hairstyle in a specific xml file, why not along with TmwAthena configuration. See the playerset handling improvement where a hairstyle node should be added.

hairstyle sample

 <?xml version="1.0"?>
   <items>
    ...
    <item id="-9" type="hairsprite" name="Short and curly">
        <sprite>hairstyle9.xml</sprite>
    </item>
    ...
   </items>

Parameter name	Type & Range	Description
id (for hairstyles)	integer From -1 to -16?? : What is the higher negative available value?	The id used by both the client and the TmwAthena server to cope with this hairstyle.
name (for hairstyles)	string	The Hair Style name.

See the <sprite> childnode description to get more information about the <sprite></sprite> part.

Note: : The ManaServ client is using this hairstyle system for now and the server doesn't support more than one race. See the playerset handling improvement where a race parameter should be added for both.

race sample

 <?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>

Parameter name	Type & Range	Description
id (for racesprites)	integer From -100 to ?? : What is the higher negative available value?	The id used by both the client and the TmwAthena server to cope with this race.
name (for hairstyles)	string	The race name.

See the <sprite> childnode description to get more information about the <sprite></sprite> part.

These low-id weapon are used to set which animation goes with which weapon for TmwAthena clients only.

weapons sample

 <?xml version="1.0"?>
   <items>
    ...
    <item id="33" weapon_type="1">
        <sprite>weapon-dagger.xml</sprite>
        <sound event="strike">weapons/swords/short-sword-miss1.ogg</sound>
        <sound event="hit">weapons/swords/short-sword-hit1.ogg</sound>
    </item>
    ...
   </items>

See the <sprite> childnode description and the <sound> childnode description to get more information about the <sprite></sprite> and the <sound></sound> part.

Those <item> parameters are used only by TmwAthena clients.

This childnode is used to provide information about how to display the item's sprite by the client. This node is used by the client only and is very recommended.

sprite sample

 <?xml version="1.0"?>
   <items>
    ...
    <item id="523" image="armor-chest-leathershirt.png" name="Leather Shirt">
        <sprite gender="male">chest-leather-male.xml|#573a26,9e7654,d3b79e,ffffff;#b96b3d,fbf5f1</sprite>
        <sprite gender="female">chest-leather-female.xml|#412300,603100,8d4900;#ffff00</sprite>
    </item>
    ...
 </items>

This childnode is used to provide information about which sound are to be played by the client, based on the actions made with the given the item. This node is used by the client only.

sound sample

 <?xml version="1.0"?>
   <items>
    ...
     <item id="521"
      image="weapon-dagger-dagger.png"
      name="Dagger">
        <sprite>weapon-dagger.xml</sprite>
        <sound event="strike">weapons/swords/short-sword-miss1.ogg</sound>
        <sound event="hit">weapons/swords/short-sword-hit1.ogg</sound>
    </item>
    ...
 </items>

This childnode is used to provide information about what the server should do when dealing with an item. This node is used by the client and manaserv v1 to define advanced items behaviour, and replace old hp, mp, script parameters, …

Note that an item can have more than one effect, and more than one effect per type.

effect sample

 <?xml version="1.0"?>
   <items>
    ...
     <item id="1"
      image="candy.png"
      name="Dagger">
       <effect trigger="activation">
            <script src="candy.lua" function="use" />
            <consumes />
        </effect>
     </item>
     ...
     <item id="521"
      image="weapon-dagger-dagger.png"
      name="Dagger">
        <sprite>weapon-dagger.xml</sprite>
        <effect trigger="in-inventory">
             <modifier attribute="cap1" value="-2000" />
        </effect>
        <effect trigger="equip">
            <autoattack skill="100" warmupspeed="10" cooldownspeed="166"
            basedamage="50" deltadamage="10" chancetohit="2" range="32"
            element="neutral" damagetype="physical" />
            <modifier attribute="acc1" value="1.5" />
        </effect>
    </item>
    ...
 </items>

Parameter name	Type	Mandatory	Default value	Description
trigger	string	Yes	”” Must be one of the predefined parameters.	This parameter is used to tell when the effect should be triggered. The folloing events can be triggered: in-inventory: This event is triggered when the item is in the player inventory. activation: This event is triggered when the item is used/activated. leave-inventory: Triggered when leaving the inventory. (Dropped, consumed after use, sold, traded, …) equip: Triggered when the player equips the item. (Note: When the item is equippable, it isn't stackable anymore. i.e.: The max-per-slot parameter it reset to 1.) unequip: Triggered when the player unequips the item. equip-change: Triggered when an equipped item is replace by another. Note that this item will also trigger the equip event of the newly equipped item, and the unequip trigger of the current item. : This is redundant in 99% of the cases and may be removed in near future.
<consumes /> sub-childnode
The only presence of this tag is sufficient to tell the server that the item must be removed after triggering that event. Hence, it will be used mostly for use-once item like simple potions, etc… but it may technically be used for any event, leading to surprising effects.
<script> sub-childnode
Parameter name	Type	Mandatory	Default value	Description
src	string	Yes	””	The script filename to use when activating/deactivating the item. The file is relative to the data/scripts/items/ folder.
function	string	Yes	””	The script function called in the script file when activating the item. Note that two parameters are pushed to this function: The item user being pointer, and the item Id. Your function can have the following form: function activate_function_name(user, item_id), for instance.
dispell-function	string	Yes	””	The script function called in the script file when deactivating the item. Note that two parameters are pushed to this function: The item user being pointer, and the item Id. Your function can have the following form: function activate_function_name(user, item_id), for instance.
Note: Item can't use the built-in schedule functions at the moment!
<modifier> sub-childnode
Modifiers are here to modify attributes when an event is triggered. An item can have 0 to many modifiers for each event.
Parameter name	Type	Mandatory	Default value	Description
attribute	string	Yes	””	This value must correspond to one of the tag parameter present in the <modifier> node of the attributes.xml file. They are used to trigger an effect on the player's attributes. I.e.: Increasing or decreasing strength when equipped, raise speed when activated, ect…
value	integer	Yes	0	This value indicates of how much the effect on the attribute tag is applied. The actual effect is depending on how you've configured the attribute's modifier.
<autoattack> <effect> childnode (: Should that be renamed attack, simply?)
Autoattacks are attack specifications used by the server to determine the damage value, type, and frequency of a player when using the associated weapon. Autoattacks are still under heavy development, so don't expect it to work atm.
Parameter name	Type	Mandatory	Default value	Description
skill	string/integer	Yes	default skill	The skill id or name (Do prefer the id when you're using non english names) of the associated skill defined in the skills.xml file that will receive the XP earned when the player will use the weapon and win over a monster.
warmupspeed	integer	Yes	0	The warmup speed is the time in millisecond the player will have to wait before actually do a blow to its enemy. See that as the time you need to bend your bow before shooting, for instance.
cooldownspeed	integer	Yes	0	The cooldown speed is the time in millisecond the player will have to wait after a strike before being able to attack once again. See that as the time you need to rearm your bow before bending it once again, for instance.
basedamage	integer	Yes	0	The base damage value is the minimal raw damage value you will deal to the enemy, minus their defence value.
chancetohit	integer	Yes	0	The chance to hit is a value added (or removed if negative) to the player accuracy value. Note that the accuracy, and thus the chancetohit are relative to the opponent's own evade value. : Attest all that and fix discrepancies.
range	integer	Yes	16	The range value is the weapon range in pixels. When using 32 pixel-wide tiles, the weapon will be able to inflict damage one tile away from the player position. Note that the player radius isn't taken in account atm.
element	string	No	“neutral”	: This isn't implemented at all atm. The attack element will permit to change the damage calculation based on the opponent's element weaknesses and strengths.
damagetype	string	Yes	Defined values: physical magical direct	The damage type is used to know how to compute the damage. A physical damage will likely take the physical defence of the enemy, a magical one will likely take into account the magical attributes of the player and its opponent, and their elements. A direct one is a “deal this without any change” damage value.

: The definitions are to be tested and fixed when needed. Autotattacks are known to be fixed first, atm, for instance.

This childnode is used to provide sprite and particle information for the item when it is on the floor. This can contain <sprite> and <particlefx> tags, which function as above.

floor sample

 <?xml version="1.0"?>
   <items>
    ...
     <item id="1"
      image="candy.png"
      name="Candy">
       <floor>
            <sprite>candy-floor.xml</sprite>
            <particlefx>fresh-food.xml</particlefx>
        </floor>
     </item>
    ...
 </items>