#textdomain wesnoth
# This file contains unit utility macros for WML authors.
#
# These don't rely on any other macros.   Please don't change this.

# This needs to match the magic UNREACHABLE constant in unit_movement_type
#define UNREACHABLE
99 #enddef

# Use this to restrict a filter to on-map units, not the recall list.
#define NOT_ON_RECALL_LIST
    [not]
        x,y=recall,recall
    [/not]
#enddef

# Rationale for the naming scheme of these generators:
# All generators take SIDE X Y for consistency.
# Those that begin with NAMED_ additionally take ID_STRING NAME_STRING
# The LOYAL_ macros set the loyalty trait.

#define UNIT SIDE TYPE X Y WML
    # Place a unit with embedded WML specified.
    #
    [unit]
        side={SIDE}
        type={TYPE}
        x={X}
        y={Y}
        {WML}
    [/unit]
#enddef

#define GENERIC_UNIT SIDE TYPE X Y
    # Creates a generic unit of TYPE belonging to SIDE at X,Y, which has a
    # random name, gender and traits (just like a recruited unit).
    [unit]
        side={SIDE}
        type={TYPE}
        x={X}
        y={Y}
        generate_name=yes
        random_traits=yes
        random_gender=yes
        upkeep=full
    [/unit]
#enddef

#define NOTRAIT_UNIT SIDE TYPE X Y
    # Creates a unit with no traits, random gender and generated name.
    #
    # Example:
    #! {NOTRAIT_UNIT 1 (Elvish Fighter) 19 16}
    #
    [unit]
        side={SIDE}
        type={TYPE}
        x={X}
        y={Y}
        generate_name=yes
        random_traits=no
        random_gender=yes
    [/unit]
#enddef

#define LOYAL_UNIT SIDE TYPE X Y
    # Creates a unit with the Loyal trait.
    #
    # Example:
    #! {LOYAL_UNIT 1 (Elvish Fighter) 19 16}
    #
    [unit]
        type={TYPE}
        side={SIDE}
        x={X}
        y={Y}
        generate_name=yes
        [modifications]
            {TRAIT_LOYAL}
        [/modifications]
    [/unit]
#enddef

#define NAMED_UNIT SIDE TYPE X Y ID_STRING NAME_STRING WML
    # Place a named unit with embedded WML specified.
    #
    [unit]
        side={SIDE}
        type={TYPE}
        x={X}
        y={Y}
        id={ID_STRING}
        name={NAME_STRING}
        {WML}
    [/unit]
#enddef

#define NAMED_LOYAL_UNIT SIDE TYPE X Y ID_STRING NAME_STRING
    # Creates a unit with the Loyal trait.
    #
    # Example:
    #! {NAMED_LOYAL_UNIT 1 (Elvish Fighter) 19 16 (Myname) ( _ "Myname")}
    #
    [unit]
        side={SIDE}
        type={TYPE}
        id={ID_STRING}
        name={NAME_STRING}
        x={X}
        y={Y}
        [modifications]
            {TRAIT_LOYAL}
        [/modifications]
    [/unit]
#enddef

#define NAMED_GENERIC_UNIT SIDE TYPE X Y ID_STRING NAME_STRING
    # Creates a generic unit of TYPE belonging to SIDE at X,Y, which has a
    # generated gender and traits (just like a recruited unit).
    # FEMALE_NAME may also be specified, mainly for translation purposes.
    #
    # Example:
    #! {NAMED_NOTRAIT_UNIT 1 (Dark Sorcerer) 20 22 (Guard) (_"Dark Sorcerer")
    #!  FEMALE_NAME=_"female^Dark Sorceress"}
    #
#arg FEMALE_NAME
{NAME_STRING}#endarg
    [unit]
        side={SIDE}
        type={TYPE}
        id={ID_STRING}
        name={NAME_STRING}
        female_name={FEMALE_NAME}
        x={X}
        y={Y}
        random_traits=yes
        random_gender=yes
        upkeep=full
    [/unit]
#enddef

#define NAMED_NOTRAIT_UNIT SIDE TYPE X Y ID_STRING NAME_STRING
    # Creates a unit with no traits, random gender and specified name.
    # FEMALE_NAME may also be specified, mainly for translation purposes.
    #
    # Example:
    #! {NAMED_NOTRAIT_UNIT 1 (Mage) 20 22 (Mochi) (_"Mochi")
    #!  FEMALE_NAME=_"female^Mochi"}
    #
#arg FEMALE_NAME
{NAME_STRING}#endarg
    [unit]
        side={SIDE}
        type={TYPE}
        id={ID_STRING}
        name={NAME_STRING}
        female_name={FEMALE_NAME}
        x={X}
        y={Y}
        random_traits=no
        random_gender=yes
    [/unit]
#enddef

#define RECALL ID_STRING
    [recall]
        id={ID_STRING}
    [/recall]
#enddef

#define RECALL_XY ID_STRING X Y
    # Note that id precedes x and y, unlike with the unit-generating macros.
    [recall]
        id={ID_STRING}
        x={X}
        y={Y}
    [/recall]
#enddef

#define GUARDIAN
    # Meant to be used as a suffix to a unit-generating macro call.
    [+unit]
        ai_special=guardian
    [/unit]
#enddef

#define NO_UPKEEP
    # Meant to be used as a suffix to a unit-generating macro call.
    # Use this when you don't want to use up a traits slot.
    [+unit]
        [+modifications]
            {TRAIT_LOYAL}
            [+trait]
                male_name=""
                female_name=""
            [/trait]
        [/modifications]
    [/unit]
#enddef

#define FACING DIRECTION
    # Meant to be used as a suffix to a unit-generating macro call.
    [+unit]
        facing={DIRECTION}
    [/unit]
#enddef

#define VARIATION VARIATION_NAME
    # Meant to be used as a suffix to a unit-generating macro call.
    [+unit]
        variation={VARIATION_NAME}
    [/unit]
#enddef

#define PASSABLE_HEX
    # Meant to be used as a suffix to a unit-generating macro call.
    # Makes sure the generated unit is in a passable hex
    [+unit]
        passable=yes
    [/unit]
#enddef

#define STORE_UNIT_VAR FILTER VAR TO_VAR_NAME
    # Stores an attribute of a unit to the given variable.
    #
    # Example where this is used to flip all orcs to whatever side James is on:
    #! {STORE_UNIT_VAR (id=James) side side_of_James}
    #! {MODIFY_UNIT (race=orc) side $side_of_James}
    #! {CLEAR_VARIABLE side_of_James}
    [store_unit]
        [filter]
            {FILTER}
        [/filter]

        kill=no
        variable=STORE_UNIT_VAR_store
    [/store_unit]

    [set_variable]
        name={TO_VAR_NAME}
        value=$STORE_UNIT_VAR_store.{VAR}
    [/set_variable]

    [clear_variable]
        name=STORE_UNIT_VAR_store
    [/clear_variable]
#enddef

#define ADVANCE_UNIT FILTER ID_STRING
    # Advances all units matching the filter to ID_STRING or if missing, their normal advancement
    #
    # Example to advance all spearmen to a cavalrymen:
    #! {ADVANCE_UNIT type=Spearman Cavalryman}
    # Example to advance your leader normally:
    #! {ADVANCE_UNIT canrecruit,side=yes,1 ""}

    [modify_unit]
        [filter]
            {FILTER}
        [/filter]
        type={ID_STRING}
    [/modify_unit]
#enddef

#define TRANSFORM_UNIT FILTER TYPE
    # Transforms all units matching the filter into TYPE or if missing, their normal advancement
    # Keeps the unit's hitpoints, experience and status intact.
    #
    # Example to turn all spearmen into cavalrymen:
    #! {TRANSFORM_UNIT type=Spearman Cavalryman}

    [transform_unit]
        {FILTER}
        transform_to={TYPE}
    [/transform_unit]
#enddef

#define WOUNDED_UNIT OTHER_FILTERS
    # Currently used in sprite animations, see also STANDARD_IDLE_FILTER in animation-utils.cfg

    [filter]
        formula="if(self.hitpoints <= self.max_hitpoints / 3, 1, 0)"
        {OTHER_FILTERS}
    [/filter]
#enddef