specials.xml

Overview

Specials in the Mana server are special attacks or abillities by characters that are actively triggered by the player. For example magic spells, special attacks or specific actions of the character can be implemented using specials.

XML Structure

The specials.xml file is used to set up the different special moves and capacity used by the player while in game.

Warning: WIP Currently, the implementation isn't fully tested. Feel free to report bug in our mantis.

Here is an example of a specials.xml file:

<?xml version="1.0" encoding="utf-8"?>
<specials>
    <set name="Magic">
        <special
            id="1"
            name="Test Spell 1"
            rechargeable="true"
            needed="100"
            rechargespeed="10"
            icon="icons/spell_1.png"
        />
        <special
            id="2"
            name="Test Spell 2"
            rechargeable="true"
            needed="1000"
            rechargespeed="10"
            target="being"
            icon="icons/spell_2.png"
        />
    </set>
</specials>

`skills` node
`set` child node
Parameter name	Type	Required in client	Required in account-server	Required in game-server	Default value	Description
name	**string**	yes	no	no	""	The special group name. Sets are used to visually group specials in the same tab in the client's specials window.
`special` child node
Parameter name	Type	Required in client	Required in account-server	Required in game-server	Default value	Description
id	**integer**	yes	yes	yes	0	The special Id used internally. Must be \> 0 and unique.
name	**string**	yes	yes	yes	-	The special name.
icon	**string**	no	no	no	""	The icon image displayed in the client.
rechargeable	**boolean**	yes	no	yes	"true"	Whether the special is rechargeable. Unrechargable specials are possible to use any time without the need to wait for a reload.
needed	**integer**	yes	no	yes	0	The amount of `mana` that the specials needs to be triggered (Obsolete if `rechargable` is false.
rechargespeed	**integer**	no	no	yes	0	The default recharge of `mana` per game tick (100ms). Overwriteable for each character using scripts. Obsolete if `rechargable` is false.
target	**string**	yes	no	yes	"being"	The target mode of the special. Possible values: "being" - targets beings "point" - targets a point on the map (**CLIENT IS LACKING SUPPORT**) If you do not need a target simply set it to "being".

A script example

Here is an example special. It implements a heal spell that can heal other people or yourself. The example also shows how it is possible to link the specials to skills.

First the needed entry in the specials.xml:

        <!-- ... -->
        <special
            id="4"
            name="Heal"
            rechargeable="true"
            needed="17500"
            rechargespeed="175"
        />
        <!-- ... -->

Then the definition in the skills.xml. This is of course only needed if you want to link the special to a skill. This is not directly needed for specials. It is only needed in this example.

    <!-- ... -->
    <set name="Magic">
        <!-- ... -->
        <skill id="203" name="Heal"
            icon="icons/spell_heal.png"/>
        <!-- ... -->
    </set>
    <!-- ... -->

And finally the lua script (see the scripting documentation for more info):

local skill_name = "Magic_Heal"
local heal = 20
local range = 6 * TILESIZE

-- Here we get the special info by the name (<setname>_<specialname>)
-- For getting it by id simply use the id instead of a string.
local spell = get_special_info("Magic_Heal")
spell:on_use(function(user, target, special_id)
    -- Either target a player or if no target is selected the user
    target = target or user
    if being_type(target) ~= TYPE_CHARACTER and target ~= user then
        return
    end 

    local heal_mod = heal * get_special_factor(user, skill_name)

    -- Spawn a effect on the target
    effect_create(11, target)

    -- Calculate the effect of heal
    local current_hp = being_get_modified_attribute(target, ATTR_HP)
    local max_hp = being_get_modified_attribute(target, ATTR_MAX_HP)

    heal_mod = math.min(heal_mod, max_hp - current_hp)
    local gained_exp = math.floor(heal_mod / 10) 

    -- Stop since nothing would be healed
    if heal_mod == 0 then
        return
    end 

    -- Actually do the healing
    being_set_base_attribute(target, ATTR_HP, current_hp + heal_mod)

    -- No exp for self heal
    if target ~= user then
        -- This gives the player XP for the Heal skill.
        -- As mentioned before, linking with skills if of course fully optional and not required.
        chr_give_exp(user, skill_name, gained_exp)
    end

    -- Consume the mana --> Force the special to recharge
    chr_set_special_mana(user, special_id, 0)
end)

So the structure of a special generally looks like this:

-- Here we get the special info by the name (<setname>_<specialname>)
-- For getting it by id simply use the id instead of a string.
local spell = get_special_info("setname_specialname")
spell:on_use(function(user, target, special_id)

    -- Define the effect of the special here!

    -- Consume the mana --> Force the special to recharge
    chr_set_special_mana(user, special_id, 0)
end)