The Battle for Wesnoth Wiki - User contributions [en]

MultiplayerContent

2025-12-17T20:16:56Z

Shiki: /* Other Notes */ no/yes

{{Translations}}
{{Create}}

This page is dedicated to the syntax modifications necessary to enable a scenario or campaign to work in multiplayer mode. Only the differences between multiplayer and singleplayer are documented here, so you might want to read [[BuildingScenarios]] and [[BuildingCampaigns]] first.

<b>Note:</b> This page assumes you have a basic add-on set up as described in [[AddonStructure]], as well as some coded content.

== Multiplayer scenarios ==

You can play standalone scenarios in multiplayer mode without setting up a campaign (this isn't possible in singleplayer). Simply make the following modifications:

* In the _main.cfg file, use <b>#ifdef MULTIPLAYER</b> as the load conditional
* In the scenario configuration file, use a toplevel <b>[multiplayer]</b> tag instead of <b>[scenario]</b> tag

== Multiplayer campaigns ==

<b>Note:</b> This section is relevant for version '''1.11.6 and higher'''.

Wesnoth has basic support for campaigns that can be played in multiplayer mode, with your friends, or even with an AI. There will still be some things that don't work as expected since some functionality for multiplayer campaigns is still being developed. While you can and should test your work in hotseat mode, there are a number of things that might behave differently under real network conditions (mostly affecting scenario and side parameters). Keep this in mind and make sure to test your campaign over the net, too.

==== The Campaign Tag ====

Multiplayer campaigns use the [campaign] tag, thus allowing the same campaign to work both in both modes. The only difference is that game also checks for a couple optional tags when campaign is used in multiplayer. They could be found on the [[CampaignWML]] page. Additionally, the '''type''' attribute should be explicitly set to '''mp''' or '''hybrid''' or otherwise a campaign would not be visible in multiplayer.

==== The Scenario File ====

A scenario in a multiplayer campaign is almost identical to a scenario in a singleplayer campaign. You only need to change the following:

* Every scenario which should not be available to start directly, should have '''allow_new_game=no''' inside the [scenario] tag. This will prevent it from showing as an "entry point" in the multiplayer configuration screen. {{DevFeature1.13|?}} This is no longer true, '''allow_new_game=no''' is now the default
* For scenarios that don't use '''allow_new_game=no''', one could make use of '''new_game_title''' to have a custom title. This is useful if the campaign is supposed to have multiple entry points such as chapters.
* Each human-controlled side needs to have a '''controller=human''' key defined in its [side] tag to work in network mode.
* Each human-controlled side also needs to have a '''save_id''' defined inside its [side] tag. Each side's save_id should be unique, and it should be the same in every scenario. Without this, your recall lists and leaders will not carry over from one scenario to the next. {{DevFeature1.13|?}} This is no longer true, '''save_id''' defaults to '''id''', just like in sp
* If you want to carry over information for ai sides, they need to have a '''save_id''' defined and '''persistent=yes''' in their [side] tags. (The same is true for singleplayer campaigns)
* {{DevFeature1.13|?}} You can use '''previous_save_id''' to tell the engine which player shodul control which side. For example if you have a multiplayer campaign and in scenario1 you have two sides with ids Kalenz and Landar, and in scenario2 you have sides with ids Konrad and Delfador you can use '''previous_save_id=Kalenz''' and '''previous_save_id=Landar''' in scenario2 to make sure that the player that previously controlled Kalenz now controls Konrad and the player that previously controlled Landar now controlls Delfador.

== Other Notes ==

* To ensure that your scenario settings won't get overwritten by the settings from the multiplayer configure dialog, you can set '''force_use_map_settings=yes'''. However, if your campaign is not intended to be played strictly with default settings, you can set it to '''no'''.

* If any settings are still taken from the multiplayer configure dialog, it is possible to overwrite them in the prestart event. Useful tags include [set_recruit], [modify_side], [modify_turns],[remove_shroud], and [lift_fog]. You might also want to use <b>experience_modifier=100</b> in the [scenario] tag.

==== Synchronization ====

When creating multiplayer content, you should be cautious of code that might change on one client but not the other players'. Not doing so can result in an [[OOS_(Out_of_Sync) | Out of Sync]] error. Most [event]s are synced across all clients, but a few still have issues. A full list of safe events can be found on the [[EventWML#Multiplayer_safety | EventWML]] page.

== See Also ==

* [[Create]]
* [[BuildingScenarios]]
* [[BuildingCampaigns]]

[[Category:Create]]

AbilitiesWML

2025-12-16T02:21:36Z

Shiki: variable name

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be choosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[heals]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a value
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a value
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* Use Common keys and tags for abilities with a value
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

UnitTypeWML

2025-12-16T01:27:50Z

Shiki: /* Attacks */ change link

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version <b>1.14.3</b>.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.<br/>WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.<br/>{{DevFeature1.17|26}} canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in [https://github.com/wesnoth/wesnoth/pull/8375 8375].
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [[UnitsWML#.5Brace.5D|[race]]] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:
** ''scout'': Fast, mobile unit meant for exploration and village grabbing.
** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.
** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.
** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.
** ''healer'': Specialty 'heals' or 'cures'.
:Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''specials_list''': {{DevFeature1.19|18}} A comma-separated list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]], these will be added to this attack as if their full definition was included in '''[specials]'''. Example: ''specials_list=plague,magical''.
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} decouples the attack's alignment from the unit's alignment. One of ''lawful'', ''neutral'', ''chaotic'', ''liminal'' (See [[TimeWML]]). If unspecified, the unit alignment is used. Only useful for units with multiple attacks, otherwise you can change the unit alignment instead.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]
* '''abilities_list''': {{DevFeature1.19|18}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this unit type as if their full definition was included in '''[abilities]'''. Example: ''abilities_list=heals_8,regenerates''.

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities|WML Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

Template:Lua Functions

2025-12-16T01:18:59Z

Shiki: Add wesnoth.map.iter_adjacent to the listing

{| class="reference-sidebar"
|
<span class="editlink">[[{{SERVER}}{{localurl:Template:Lua Functions|action=edit}} edit]]</span>'''Lua Functions'''
|-
|''wesnoth''
[[LuaAPI/wesnoth#wesnoth.as_text|wesnoth.as_text]]<br>
[[LuaAPI/wesnoth#wesnoth.colors|wesnoth.colors]]<br>
[[LuaAPI/wesnoth#wesnoth.compile_formula|wesnoth.compile_formula]]<br>
[[LuaAPI/wesnoth#wesnoth.current|wesnoth.current]]<br>
[[LuaAPI/wesnoth#wesnoth.current_version|wesnoth.current_version]]<br>
[[LuaAPI/wesnoth#wesnoth.custom_synced_commands|wesnoth.custom_synced_commands]]<br>
[[LuaAPI/wesnoth#wesnoth.deprecate_api|wesnoth.deprecate_api]]<br>
[[LuaAPI/wesnoth#wesnoth.deprecated_message|wesnoth.deprecated_message]]<br>
[[LuaAPI/wesnoth#wesnoth.dofile|wesnoth.dofile]]<br>
[[LuaAPI/wesnoth#wesnoth.effects|wesnoth.effects]]<br>
[[LuaAPI/wesnoth#wesnoth.eval_formula|wesnoth.eval_formula]]<br>
[[LuaAPI/wesnoth#wesnoth.game_config|wesnoth.game_config]]<br>
[[LuaAPI/wesnoth#wesnoth.get_language|wesnoth.get_language]]<br>
[[LuaAPI/wesnoth#wesnoth.log|wesnoth.log]]<br>
[[LuaAPI/wesnoth#wesnoth.micro_ais|wesnoth.micro_ais]]<br>
[[LuaAPI/wesnoth#wesnoth.ms_since_init|wesnoth.ms_since_init]]<br>
[[LuaAPI/wesnoth#wesnoth.name_generator|wesnoth.name_generator]]<br>
[[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]]<br>
[[LuaAPI/wesnoth#wesnoth.persistent_tags|wesnoth.persistent_tags]]<br>
[[LuaAPI/wesnoth#wesnoth.print_attributes|wesnoth.print_attributes]]<br>
[[LuaAPI/wesnoth#wesnoth.races|wesnoth.races]]<br>
[[LuaAPI/wesnoth#wesnoth.require|wesnoth.require]]<br>
[[LuaAPI/wesnoth#wesnoth.scenario|wesnoth.scenario]]<br>
[[LuaAPI/wesnoth#wesnoth.simulate_combat|wesnoth.simulate_combat]]<br>
[[LuaAPI/wesnoth#wesnoth.terrain_types|wesnoth.terrain_types]]<br>
[[LuaAPI/wesnoth#wesnoth.textdomain|wesnoth.textdomain]]<br>
[[LuaAPI/wesnoth#wesnoth.type|wesnoth.type]]<br>
[[LuaAPI/wesnoth#wesnoth.unit_types|wesnoth.unit_types]]<br>
[[LuaAPI/wesnoth#wesnoth.version|wesnoth.version]]<br>
[[LuaAPI/wesnoth#wesnoth.wml_actions|wesnoth.wml_actions]]<br>
[[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]]<br>
|-
|''wesnoth.achievements''
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.get|wesnoth.achievements.get]]<br>
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has|wesnoth.achievements.has]]<br>
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has_sub_achievement|wesnoth.achievements.has_sub_achievement]]<br>
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.progress|wesnoth.achievements.progress]]<br>
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set|wesnoth.achievements.set]]<br>
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set_sub_achievement|wesnoth.achievements.set_sub_achievement]]<br>
|-
|''wesnoth.audio''
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list|wesnoth.audio.music_list]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.add|wesnoth.audio.music_list.add]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.all|wesnoth.audio.music_list.all]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.clear|wesnoth.audio.music_list.clear]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.current|wesnoth.audio.music_list.current]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.next|wesnoth.audio.music_list.next]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.play|wesnoth.audio.music_list.play]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.previous|wesnoth.audio.music_list.previous]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.remove|wesnoth.audio.music_list.remove]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.volume|wesnoth.audio.music_list.volume]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.play|wesnoth.audio.play]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.sources|wesnoth.audio.sources]]<br>
[[LuaAPI/wesnoth/audio#wesnoth.audio.volume|wesnoth.audio.volume]]<br>
|-
|''wesnoth.game_events''
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add|wesnoth.game_events.add]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_menu|wesnoth.game_events.add_menu]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_repeating|wesnoth.game_events.add_repeating]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_wml|wesnoth.game_events.add_wml]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire_by_id|wesnoth.game_events.fire_by_id]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_event|wesnoth.game_events.on_event]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_load|wesnoth.game_events.on_load]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_action|wesnoth.game_events.on_mouse_action]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_button|wesnoth.game_events.on_mouse_button]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_move|wesnoth.game_events.on_mouse_move]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_save|wesnoth.game_events.on_save]]<br>
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.remove|wesnoth.game_events.remove]]<br>
|-
|''wesnoth.interface''
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_chat_message|wesnoth.interface.add_chat_message]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_hex_overlay|wesnoth.interface.add_hex_overlay]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_halo|wesnoth.interface.add_item_halo]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_image|wesnoth.interface.add_item_image]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_overlay_text|wesnoth.interface.add_overlay_text]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.allow_end_turn|wesnoth.interface.allow_end_turn]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.clear_chat_messages|wesnoth.interface.clear_chat_messages]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.color_adjust|wesnoth.interface.color_adjust]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.delay|wesnoth.interface.delay]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.deselect_hex|wesnoth.interface.deselect_hex]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.end_turn|wesnoth.interface.end_turn]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.float_label|wesnoth.interface.float_label]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit|wesnoth.interface.get_displayed_unit]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_hovered_hex|wesnoth.interface.get_hovered_hex]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_items|wesnoth.interface.get_items]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_selected_hex|wesnoth.interface.get_selected_hex]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_viewing_side|wesnoth.interface.get_viewing_side]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.handle_user_interact|wesnoth.interface.handle_user_interact]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.highlight_hex|wesnoth.interface.highlight_hex]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_locked|wesnoth.interface.is_locked]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_skipping_messages|wesnoth.interface.is_skipping_messages]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.lock|wesnoth.interface.lock]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_hex_overlay|wesnoth.interface.remove_hex_overlay]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_item|wesnoth.interface.remove_item]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll|wesnoth.interface.scroll]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex|wesnoth.interface.scroll_to_hex]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.select_unit|wesnoth.interface.select_unit]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.skip_messages|wesnoth.interface.skip_messages]]<br>
[[LuaAPI/wesnoth/interface#wesnoth.interface.zoom|wesnoth.interface.zoom]]<br>
|-
|''wesnoth.map''
[[LuaAPI/wesnoth/map#wesnoth.map.add_label|wesnoth.map.add_label]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.are_hexes_adjacent|wesnoth.map.are_hexes_adjacent]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.create|wesnoth.map.create]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.distance_between|wesnoth.map.distance_between]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.find|wesnoth.map.find]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.generate|wesnoth.map.generate]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.generate_height_map|wesnoth.map.generate_height_map]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get|wesnoth.map.get]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_adjacent_hexes|wesnoth.map.get_adjacent_hexes]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_area|wesnoth.map.get_area]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_direction|wesnoth.map.get_direction]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_hexes_in_radius|wesnoth.map.get_hexes_in_radius]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_label|wesnoth.map.get_label]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_owner|wesnoth.map.get_owner]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.get_relative_dir|wesnoth.map.get_relative_dir]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.iter|wesnoth.map.iter]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.iter_adjacent|wesnoth.map.iter_adjacent]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.make_bitmap|wesnoth.map.make_bitmap]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.matches|wesnoth.map.matches]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.on_board|wesnoth.map.on_board]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.on_border|wesnoth.map.on_border]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.place_area|wesnoth.map.place_area]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.read_location|wesnoth.map.read_location]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.remove_area|wesnoth.map.remove_area]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.remove_label|wesnoth.map.remove_label]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.rotate_right_around_center|wesnoth.map.rotate_right_around_center]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.set_owner|wesnoth.map.set_owner]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.split_terrain_code|wesnoth.map.split_terrain_code]]<br>
[[LuaAPI/wesnoth/map#wesnoth.map.terrain_mask|wesnoth.map.terrain_mask]]<br>
|-
|''wesnoth.paths''
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_cost_map|wesnoth.paths.find_cost_map]]<br>
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_path|wesnoth.paths.find_path]]<br>
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_reach|wesnoth.paths.find_reach]]<br>
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vacant_hex|wesnoth.paths.find_vacant_hex]]<br>
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vision_range|wesnoth.paths.find_vision_range]]<br>
|-
|''wesnoth.schedule''
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_illumination|wesnoth.schedule.get_illumination]]<br>
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_time_of_day|wesnoth.schedule.get_time_of_day]]<br>
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.replace|wesnoth.schedule.replace]]<br>
|-
|''wesnoth.sides''
[[LuaAPI/wesnoth/sides#wesnoth.sides.add_ai_component|wesnoth.sides.add_ai_component]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.append_ai|wesnoth.sides.append_ai]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.change_ai_component|wesnoth.sides.change_ai_component]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.create|wesnoth.sides.create]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.debug_ai|wesnoth.sides.debug_ai]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.delete_ai_component|wesnoth.sides.delete_ai_component]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.find|wesnoth.sides.find]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.get|wesnoth.sides.get]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_enemy|wesnoth.sides.is_enemy]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_fogged|wesnoth.sides.is_fogged]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_shrouded|wesnoth.sides.is_shrouded]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.iter|wesnoth.sides.iter]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.matches|wesnoth.sides.matches]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.override_shroud|wesnoth.sides.override_shroud]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_fog|wesnoth.sides.place_fog]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_shroud|wesnoth.sides.place_shroud]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_fog|wesnoth.sides.remove_fog]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_shroud|wesnoth.sides.remove_shroud]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.set_id|wesnoth.sides.set_id]]<br>
[[LuaAPI/wesnoth/sides#wesnoth.sides.switch_ai|wesnoth.sides.switch_ai]]<br>
|-
|''wesnoth.sync''
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_multiple|wesnoth.sync.evaluate_multiple]]<br>
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_single|wesnoth.sync.evaluate_single]]<br>
[[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]]<br>
[[LuaAPI/wesnoth/sync#wesnoth.sync.run_unsynced|wesnoth.sync.run_unsynced]]<br>
|-
|''wesnoth.units''
[[LuaAPI/wesnoth/units#wesnoth.units.ability|wesnoth.units.ability]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.add_modification|wesnoth.units.add_modification]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.advance|wesnoth.units.advance]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.chance_to_be_hit|wesnoth.units.chance_to_be_hit]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.clone|wesnoth.units.clone]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.create|wesnoth.units.create]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.create_animator|wesnoth.units.create_animator]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.defense_on|wesnoth.units.defense_on]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.erase|wesnoth.units.erase]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.extract|wesnoth.units.extract]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.find|wesnoth.units.find]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.find_attack|wesnoth.units.find_attack]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_map|wesnoth.units.find_on_map]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.get|wesnoth.units.get]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.get_hovered|wesnoth.units.get_hovered]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.jamming_on|wesnoth.units.jamming_on]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.matches|wesnoth.units.matches]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.movement_on|wesnoth.units.movement_on]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.rebuild|wesnoth.units.rebuild]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.remove_modifications|wesnoth.units.remove_modifications]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.resistance_against|wesnoth.units.resistance_against]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.scroll_to|wesnoth.units.scroll_to]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.select|wesnoth.units.select]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.to_map|wesnoth.units.to_map]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.transform|wesnoth.units.transform]]<br>
[[LuaAPI/wesnoth/units#wesnoth.units.vision_on|wesnoth.units.vision_on]]<br>
|-
|''ai''
[[LuaAPI/ai#ai.aspects|ai.aspects]]<br>
[[LuaAPI/ai#ai.attack|ai.attack]]<br>
[[LuaAPI/ai#ai.check_attack|ai.check_attack]]<br>
[[LuaAPI/ai#ai.check_move|ai.check_move]]<br>
[[LuaAPI/ai#ai.check_recall|ai.check_recall]]<br>
[[LuaAPI/ai#ai.check_recruit|ai.check_recruit]]<br>
[[LuaAPI/ai#ai.check_stopunit|ai.check_stopunit]]<br>
[[LuaAPI/ai#ai.fallback_human|ai.fallback_human]]<br>
[[LuaAPI/ai#ai.get_attacks|ai.get_attacks]]<br>
[[LuaAPI/ai#ai.get_targets|ai.get_targets]]<br>
[[LuaAPI/ai#ai.move|ai.move]]<br>
[[LuaAPI/ai#ai.move_full|ai.move_full]]<br>
[[LuaAPI/ai#ai.read_only|ai.read_only]]<br>
[[LuaAPI/ai#ai.recall|ai.recall]]<br>
[[LuaAPI/ai#ai.recruit|ai.recruit]]<br>
[[LuaAPI/ai#ai.side|ai.side]]<br>
[[LuaAPI/ai#ai.stopunit_all|ai.stopunit_all]]<br>
[[LuaAPI/ai#ai.stopunit_attacks|ai.stopunit_attacks]]<br>
[[LuaAPI/ai#ai.stopunit_moves|ai.stopunit_moves]]<br>
[[LuaAPI/ai#ai.suitable_keep|ai.suitable_keep]]<br>
|-
|''filesystem''
[[LuaAPI/filesystem#filesystem.canonical_path|filesystem.canonical_path]]<br>
[[LuaAPI/filesystem#filesystem.have_asset|filesystem.have_asset]]<br>
[[LuaAPI/filesystem#filesystem.have_file|filesystem.have_file]]<br>
[[LuaAPI/filesystem#filesystem.image_size|filesystem.image_size]]<br>
[[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]]<br>
[[LuaAPI/filesystem#filesystem.resolve_asset|filesystem.resolve_asset]]<br>
|-
|''functional''
[[LuaAPI/functional#functional.choose|functional.choose]]<br>
[[LuaAPI/functional#functional.choose_map|functional.choose_map]]<br>
[[LuaAPI/functional#functional.filter|functional.filter]]<br>
[[LuaAPI/functional#functional.filter_map|functional.filter_map]]<br>
[[LuaAPI/functional#functional.find|functional.find]]<br>
[[LuaAPI/functional#functional.find_map|functional.find_map]]<br>
[[LuaAPI/functional#functional.map|functional.map]]<br>
[[LuaAPI/functional#functional.map_array|functional.map_array]]<br>
[[LuaAPI/functional#functional.reduce|functional.reduce]]<br>
[[LuaAPI/functional#functional.take_while|functional.take_while]]<br>
[[LuaAPI/functional#functional.zip|functional.zip]]<br>
|-
|''gui''
[[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition]]<br>
[[LuaAPI/gui#gui.get_user_choice|gui.get_user_choice]]<br>
[[LuaAPI/gui#gui.show_dialog|gui.show_dialog]]<br>
[[LuaAPI/gui#gui.show_help|gui.show_help]]<br>
[[LuaAPI/gui#gui.show_inspector|gui.show_inspector]]<br>
[[LuaAPI/gui#gui.show_lua_console|gui.show_lua_console]]<br>
[[LuaAPI/gui#gui.show_menu|gui.show_menu]]<br>
[[LuaAPI/gui#gui.show_narration|gui.show_narration]]<br>
[[LuaAPI/gui#gui.show_popup|gui.show_popup]]<br>
[[LuaAPI/gui#gui.show_prompt|gui.show_prompt]]<br>
[[LuaAPI/gui#gui.show_recruit_dialog|gui.show_recruit_dialog]]<br>
[[LuaAPI/gui#gui.show_recall_dialog|gui.show_recall_dialog]]<br>
[[LuaAPI/gui#gui.show_story|gui.show_story]]<br>
[[LuaAPI/gui#gui.switch_theme|gui.switch_theme]]<br>
[[LuaAPI/gui#gui.widget|gui.widget]]<br>
|-
|''location_set''
[[LuaAPI/location_set#location_set.clear|location_set.clear]]<br>
[[LuaAPI/location_set#location_set.clone|location_set.clone]]<br>
[[LuaAPI/location_set#location_set.create|location_set.create]]<br>
[[LuaAPI/location_set#location_set.diff|location_set.diff]]<br>
[[LuaAPI/location_set#location_set.empty|location_set.empty]]<br>
[[LuaAPI/location_set#location_set.filter|location_set.filter]]<br>
[[LuaAPI/location_set#location_set.get|location_set.get]]<br>
[[LuaAPI/location_set#location_set.insert|location_set.insert]]<br>
[[LuaAPI/location_set#location_set.inter|location_set.inter]]<br>
[[LuaAPI/location_set#location_set.inter_merge|location_set.inter_merge]]<br>
[[LuaAPI/location_set#location_set.invert|location_set.invert]]<br>
[[LuaAPI/location_set#location_set.iter|location_set.iter]]<br>
[[LuaAPI/location_set#location_set.of_map|location_set.of_map]]<br>
[[LuaAPI/location_set#location_set.of_pairs|location_set.of_pairs]]<br>
[[LuaAPI/location_set#location_set.of_raw|location_set.of_raw]]<br>
[[LuaAPI/location_set#location_set.of_shroud_data|location_set.of_shroud_data]]<br>
[[LuaAPI/location_set#location_set.of_triples|location_set.of_triples]]<br>
[[LuaAPI/location_set#location_set.of_wml_var|location_set.of_wml_var]]<br>
[[LuaAPI/location_set#location_set.random|location_set.random]]<br>
[[LuaAPI/location_set#location_set.remove|location_set.remove]]<br>
[[LuaAPI/location_set#location_set.size|location_set.size]]<br>
[[LuaAPI/location_set#location_set.stable_iter|location_set.stable_iter]]<br>
[[LuaAPI/location_set#location_set.symm|location_set.symm]]<br>
[[LuaAPI/location_set#location_set.to_map|location_set.to_map]]<br>
[[LuaAPI/location_set#location_set.to_pairs|location_set.to_pairs]]<br>
[[LuaAPI/location_set#location_set.to_shroud_data|location_set.to_shroud_data]]<br>
[[LuaAPI/location_set#location_set.to_stable_pairs|location_set.to_stable_pairs]]<br>
[[LuaAPI/location_set#location_set.to_triples|location_set.to_triples]]<br>
[[LuaAPI/location_set#location_set.to_wml_var|location_set.to_wml_var]]<br>
[[LuaAPI/location_set#location_set.union|location_set.union]]<br>
[[LuaAPI/location_set#location_set.union_merge|location_set.union_merge]]<br>
|-
|''mathx''
[[LuaAPI/mathx#mathx.clamp|mathx.clamp]]<br>
[[LuaAPI/mathx#mathx.lerp|mathx.lerp]]<br>
[[LuaAPI/mathx#mathx.random|mathx.random]]<br>
[[LuaAPI/mathx#mathx.random_choice|mathx.random_choice]]<br>
[[LuaAPI/mathx#mathx.round|mathx.round]]<br>
[[LuaAPI/mathx#mathx.shuffle|mathx.shuffle]]<br>
|-
|''stringx''
[[LuaAPI/stringx#stringx.anim_split|stringx.anim_split]]<br>
[[LuaAPI/stringx#stringx.escaped_split|stringx.escaped_split]]<br>
[[LuaAPI/stringx#stringx.format_conjunct_list|stringx.format_conjunct_list]]<br>
[[LuaAPI/stringx#stringx.format_disjunct_list|stringx.format_disjunct_list]]<br>
[[LuaAPI/stringx#stringx.iter_range|stringx.iter_range]]<br>
[[LuaAPI/stringx#stringx.iter_ranges|stringx.iter_ranges]]<br>
[[LuaAPI/stringx#stringx.join|stringx.join]]<br>
[[LuaAPI/stringx#stringx.join_map|stringx.join_map]]<br>
[[LuaAPI/stringx#stringx.map_split|stringx.map_split]]<br>
[[LuaAPI/stringx#stringx.parenthetical_split|stringx.parenthetical_split]]<br>
[[LuaAPI/stringx#stringx.parse_range|stringx.parse_range]]<br>
[[LuaAPI/stringx#stringx.quoted_split|stringx.quoted_split]]<br>
[[LuaAPI/stringx#stringx.split|stringx.split]]<br>
[[LuaAPI/stringx#stringx.trim|stringx.trim]]<br>
[[LuaAPI/stringx#stringx.vformat|stringx.vformat]]<br>
|-
|''unit_test''
[[LuaAPI/unit_test#unit_test.assert|unit_test.assert]]<br>
[[LuaAPI/unit_test#unit_test.assert_approx_equal|unit_test.assert_approx_equal]]<br>
[[LuaAPI/unit_test#unit_test.assert_contains|unit_test.assert_contains]]<br>
[[LuaAPI/unit_test#unit_test.assert_equal|unit_test.assert_equal]]<br>
[[LuaAPI/unit_test#unit_test.assert_greater|unit_test.assert_greater]]<br>
[[LuaAPI/unit_test#unit_test.assert_greater_equal|unit_test.assert_greater_equal]]<br>
[[LuaAPI/unit_test#unit_test.assert_in_range|unit_test.assert_in_range]]<br>
[[LuaAPI/unit_test#unit_test.assert_less|unit_test.assert_less]]<br>
[[LuaAPI/unit_test#unit_test.assert_less_equal|unit_test.assert_less_equal]]<br>
[[LuaAPI/unit_test#unit_test.assert_not_equal|unit_test.assert_not_equal]]<br>
[[LuaAPI/unit_test#unit_test.assert_nothrow|unit_test.assert_nothrow]]<br>
[[LuaAPI/unit_test#unit_test.assert_throws|unit_test.assert_throws]]<br>
[[LuaAPI/unit_test#unit_test.assert_throws_with|unit_test.assert_throws_with]]<br>
[[LuaAPI/unit_test#unit_test.fail|unit_test.fail]]<br>
[[LuaAPI/unit_test#unit_test.finish|unit_test.finish]]<br>
[[LuaAPI/unit_test#unit_test.fire_wml_menu_item|unit_test.fire_wml_menu_item]]<br>
[[LuaAPI/unit_test#unit_test.log|unit_test.log]]<br>
[[LuaAPI/unit_test#unit_test.succeed|unit_test.succeed]]<br>
[[LuaAPI/unit_test#unit_test.tostring|unit_test.tostring]]<br>
|-
|''wml''
[[LuaAPI/wml#wml.all_variables|wml.all_variables]]<br>
[[LuaAPI/wml#wml.array_access.get|wml.array_access.get]]<br>
[[LuaAPI/wml#wml.array_access.get_proxy|wml.array_access.get_proxy]]<br>
[[LuaAPI/wml#wml.array_access.set|wml.array_access.set]]<br>
[[LuaAPI/wml#wml.array_variables|wml.array_variables]]<br>
[[LuaAPI/wml#wml.attribute_count|wml.attribute_count]]<br>
[[LuaAPI/wml#wml.child_array|wml.child_array]]<br>
[[LuaAPI/wml#wml.child_count|wml.child_count]]<br>
[[LuaAPI/wml#wml.child_range|wml.child_range]]<br>
[[LuaAPI/wml#wml.clone|wml.clone]]<br>
[[LuaAPI/wml#wml.diff|wml.diff]]<br>
[[LuaAPI/wml#wml.equal|wml.equal]]<br>
[[LuaAPI/wml#wml.error|wml.error]]<br>
[[LuaAPI/wml#wml.eval_conditional|wml.eval_conditional]]<br>
[[LuaAPI/wml#wml.find_child|wml.find_child]]<br>
[[LuaAPI/wml#wml.fire|wml.fire]]<br>
[[LuaAPI/wml#wml.get_child|wml.get_child]]<br>
[[LuaAPI/wml#wml.get_nth_child|wml.get_nth_child]]<br>
[[LuaAPI/wml#wml.interpolate|wml.interpolate]]<br>
[[LuaAPI/wml#wml.literal|wml.literal]]<br>
[[LuaAPI/wml#wml.load|wml.load]]<br>
[[LuaAPI/wml#wml.matches_filter|wml.matches_filter]]<br>
[[LuaAPI/wml#wml.merge|wml.merge]]<br>
[[LuaAPI/wml#wml.parse|wml.parse]]<br>
[[LuaAPI/wml#wml.parsed|wml.parsed]]<br>
[[LuaAPI/wml#wml.patch|wml.patch]]<br>
[[LuaAPI/wml#wml.remove_child|wml.remove_child]]<br>
[[LuaAPI/wml#wml.remove_children|wml.remove_children]]<br>
[[LuaAPI/wml#wml.shallow_literal|wml.shallow_literal]]<br>
[[LuaAPI/wml#wml.shallow_parsed|wml.shallow_parsed]]<br>
[[LuaAPI/wml#wml.tag|wml.tag]]<br>
[[LuaAPI/wml#wml.tostring|wml.tostring]]<br>
[[LuaAPI/wml#wml.tovconfig|wml.tovconfig]]<br>
[[LuaAPI/wml#wml.valid|wml.valid]]<br>
[[LuaAPI/wml#wml.variables|wml.variables]]<br>
[[LuaAPI/wml#wml.variables_proxy|wml.variables_proxy]]<br>
|-
|''wml-utils''
[[LuaAPI/wml-utils#utils.check_key|utils.check_key]]<br>
[[LuaAPI/wml-utils#utils.get_sides|utils.get_sides]]<br>
[[LuaAPI/wml-utils#utils.handle_event_commands|utils.handle_event_commands]]<br>
[[LuaAPI/wml-utils#utils.optional_side_filter|utils.optional_side_filter]]<br>
[[LuaAPI/wml-utils#utils.scoped_var|utils.scoped_var]]<br>
[[LuaAPI/wml-utils#utils.set_exiting|utils.set_exiting]]<br>
[[LuaAPI/wml-utils#utils.vwriter|utils.vwriter]]<br>
|}<includeonly>[[Category:Lua Reference]]</includeonly><noinclude>A box with all the Lua functions, each one linking to the page and section they are described in. It was generated using [[/Updating|this method]]. This box should be included in [[LuaAPI|Lua reference]] page.</noinclude>

EffectWML

2025-12-16T00:30:54Z

Shiki: specials_list inside [set_specials]

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaAPI/wesnoth#wesnoth.effects]]. Some examples can be seen in [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/World_Conquest/lua/game_mechanics/effects.lua World Conquest].

[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''specials_list''': {{DevFeature1.19|18}} One can give a list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|'''unique_id''']]s. Example: ''specials_list=drains,charge''
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''[remove_specials]''': {{DevFeature1.19|6}} remove the listed specials. Use [[StandardAbilityFilter]], special removed if matches. This tag is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''set_alignment''': {{DevFeature1.19|5}} Use for this attack an alignment of '''lawful''', '''neutral''', '''chaotic''' or '''liminal'''. It will be independent of the unit's alignment. Even if the unit's alignment changes, this attack will continue to use the alignment specified here.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
** '''set_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''set_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''set''': the new amount of the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''set_total''': will set the unit's max HP to the specified value.
** '''violate_maximum''': if the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''abilities_list''': {{DevFeature1.19|18}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this effect as if their full definition was included in '''[abilities]'''. Example: ''abilities=heals_8,regenerates''.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

== Examples ==
=== Effect: apply_to = new_animation ===
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y=1,5
[/filter]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]
</syntaxhighlight>
If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y=1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable=stored_unit
[/store_unit]
[set_variables]
name=stored_unit.modifications.object
[value]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable=stored_unit
[/unstore_unit]
[/event]
</syntaxhighlight>

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

UnitTypeWML

2025-12-15T21:57:59Z

Shiki: abilities/specials registry changes

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version <b>1.14.3</b>.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.<br/>WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.<br/>{{DevFeature1.17|26}} canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in [https://github.com/wesnoth/wesnoth/pull/8375 8375].
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [[UnitsWML#.5Brace.5D|[race]]] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:
** ''scout'': Fast, mobile unit meant for exploration and village grabbing.
** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.
** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.
** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.
** ''healer'': Specialty 'heals' or 'cures'.
:Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''specials_list''': {{DevFeature1.19|18}} A comma-separated list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]], these will be added to this attack as if their full definition was included in '''[specials]'''. Example: ''specials_list=plague,magical''.
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} decouples the attack's alignment from the unit's alignment. One of ''lawful'', ''neutral'', ''chaotic'', ''liminal'' (See [[TimeWML]]). If unspecified, the unit alignment is used. Only useful for units with multiple attacks, otherwise you can change the unit alignment instead.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]
* '''abilities_list''': {{DevFeature1.19|18}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this unit type as if their full definition was included in '''[abilities]'''. Example: ''abilities_list=heals_8,regenerates''.

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities|WML Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

AbilitiesWML

2025-12-15T21:45:17Z

Shiki: unique_id moved from 1.19.17 to 1.19.18

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be choosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[heals]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a value
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a value
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* Use Common keys and tags for abilities with a value
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$value'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

UnitsWML

2025-12-15T21:23:43Z

Shiki: moved from 1.19.17 to 1.19.18

{{WML Tags}}

The '''[units]''' tag is a [[ReferenceWML#WML_toplevel_tags|top-level WML tag]] which defines the unit types that will be available in the game.

A '''[units]''' tag primarily contains [[UnitTypeWML|[unit_type]]] tags, each of which defines one unit type, and can also contain other tags, which mostly provide definitions of things like races and movement types that are used in unit type definitions.

== Subtags of [units] ==

The following tags can be used as subtags of a '''[units]''' tag.

=== [unit_type] ===

{{Main|UnitTypeWML}}

In a '''[units]''' tag, a '''[unit_type]''' tag defines a unit type.

=== [abilities] ===
{{DevFeature1.19|18}}

A registry for Abilities. Abilities can be defined here in the usual way via [[AbilitiesWML]]. Any such ability can be then added to '''[unit_type]''' or '''[effect]apply_to=new_ability''' by mentioning its '''unique_id''' (or '''id''' if unique_id is undefined) without the need to include the full ability definition.

=== [weapon_specials] ===
{{DevFeature1.19|18}}

A registry for Weapon Specials. Weapon Specials can be defined here in the usual way via [[AbilitiesWML]]. Any such weapon special can then be added to '''[unit_type][attack]''' or '''[effect]apply_to=new_attack/attack''' by mentioning its '''unique_id''' (or '''id''' if unique_id is undefined) without the need to include the full ability definition.

=== [trait] ===

The '''[trait]''' tag describes a trait. When it appears in the '''[units]''' toplevel, it describes a global trait, and all races with the attribute '''ignore_global_traits=no''' will have this trait.; it may also appear in other places.
* '''id''': unique identifier; needed for random trait generation to work properly
* '''availability''': describes whether a trait is "musthave" for a race/unit type or is available to "any" unit, including leaders. The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits.
* '''male_name''': text displayed in the status of unit with the trait if the unit is male.
* '''female_name''': text displayed in the status of unit with the trait if the unit is female.
* '''name''': text displayed in the status of unit with the trait if none of the two above is used.
* '''description''': text displayed for the description of the trait when moving the cursor over the trait.
* '''help_text''': {{DevFeature1.13|6}} text displayed for the description of the trait in the help. Defaults to ''description'' if not specified.
* '''[effect]''': described in [[EffectWML]]. More than one of these can be used.
* '''require_traits''': {{DevFeature1.17|13}} An optional comma-separated list of trait id keys that represent traits that are required by this one. Order is not important. If the unit not already has all of the traits that appear in this list, then this trait will not be generated for this unit.
* '''exclude_traits''': {{DevFeature1.17|13}} An optional comma-separated list of trait id keys that represent traits that are mutually exclusive to this one. Order is not important. If the unit already has any of the traits that appear once in this list, then this trait will not be generated for this unit. Of course, for this to really make two traits mutually exclusive, you need to add exclude_traits to both trait definitions.

=== [movetype] ===

The '''[movetype]''' tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
* '''name''': an ID for this movetype. Units with the attribute '''movement_type=''name''''' will be assigned this movetype.
* '''flies''' or {{DevFeature1.15|0}} '''flying''': either 'yes' or 'no' (default). A unit with ''flying=yes'' does not have its image's height adjusted for different terrains.
** This key corresponds to [unit]'s '''flying''' key.
** In Wesnoth 1.12 and 1.14, the value of '''flying''' sometimes overrides the value of '''flies''', but in other times '''flying''' is ignored
** {{DevFeature1.15|0}} '''flying''' always overrides the '''flies''' value, with the intention that '''flies''' will be deprecated.
* '''[special_note]''' {{DevFeature1.15|14}} note=Translatable string, which can be set if there’s something special about this movetype. It will be displayed in the unit's help page. For typical movetypes this is not set. An example are horses with the ''mounted'' movetype. See also [[UnitTypeWML#Special_Notes]].
* {{anchor|resistance|'''[resistance]'''}}: describes how much damage the unit takes from different types of attacks. The attribute '''''type''=''resistance''''' makes the unit receive ''resistance'' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.<br> The available attack types in mainline are ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', and ''arcane''.
* {{anchor|movement_costs|'''[movement_costs]'''}}: describes how fast the unit moves on different terrains. The attribute '''''terrain''=''cost''''' means that the unit will need to use ''cost'' move points to move onto that ''terrain''.
* {{anchor|vision_costs|'''[vision_costs]'''}}: describes how far the unit clears fog and shroud on different terrains. The attribute '''''terrain''=''cost''''' means that the unit will need to use ''cost'' vision points to view into that ''terrain''. (If not specified for a particular terrain, the vision cost defaults to the movement cost.)
* {{anchor|jamming_costs|'''[jamming_costs]'''}}: {{DevFeature1.13|0}} describes how far the unit interferes with the vision of other units over different terrains. This works the same as movement and vision costs. See [https://forums.wesnoth.org/viewtopic.php?f=21&t=44577&p=644985#p644985 an example of jamming here].
* {{anchor|defense|'''[defense]'''}}: describes how likely the unit is to be hit on different terrains. The attribute '''''terrain''=''defense''''' means that the unit will be hit ''defense'' percent of the time in that ''terrain''. If the defense value is negative, then that specifies an upper limit. The number in absolute terms is then also the best defense that the unit may have if there is more than one terrain type involved. For example '''forest=-70''' common for mounted units means the unit cannot get more than 30% defense on forest terrain. Regardless what other terrain the forest is on.

The available keys for the '''[movement_costs]''', '''[vision_costs]''', '''[jamming_costs]''' and '''[defense]''' tags are the '''id'''s of archetype terrains (those not aliased to any other terrain, see [[TerrainWML]]).<br>
In mainline that encompasses ''deep_water'', ''shallow_water'', ''reef'', ''swamp_water'', ''flat'', ''sand'', ''forest'', ''hills'', ''mountains'', ''village'', ''castle'', ''cave'', ''frozen'', ''unwalkable'', ''fungus'', and ''impassable''. If a particular archetype is not mentioned in a movetype, it means a unit with that movetype cannot move to a terrain with that archetype.

=== [race] ===

The '''[race]''' tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions. 'id' and 'plural_name' and ('name' or ('male_name' and 'female_name')) '''must''' be supplied.
* '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
* '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
* '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
* '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
* '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'.
* '''description''': text used in the in-game help.
* '''help_taxonomy''': {{DevFeature1.15|5}} in the help browser, show this race as a group of units from another race; the value of this attribute should be the other race's '''id''' attribute. This only affects the help browser, for all other purposes (such as WML filters) the two races are completely separate. (How this is visualised in the help browser is a GUI design decision, this attribute merely tells the engine that the relationship exists.)
* '''name_generator''' {{DevFeature1.13|5}}: [[Context-free grammar]] describing unit names, if absent or invalid, falls back to male_names or female_names
* '''male_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for male names
* '''female_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for female names
* '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
* '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
* '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
* '''ignore_global_traits''': 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.
* '''undead_variation''': sets the default undead variation for members of this race.
* '''[topic]''': describes extra help topics for this race.
* '''[trait]''': describes a trait for this race. See above for syntax.

=== [resistance_defaults] ===

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.9 ([https://github.com/wesnoth/wesnoth/issues/5308 issue #5308])

The '''[resistance_defaults]''' tag allows you to add resistance for custom damage types to already-defined movetypes (such as core movetypes).
* '''id''': The damage type you want to apply resistance defaults for.
* '''default''': The default resistance for all movetypes. You can set it to a number, or to a [[Wesnoth Formula Language|formula]] (enclosed in parentheses, but with no preceding dollar sign <code>$</code> or whitespace) which can reference any of the default resistance types - arcane, fire, etc. A common usage for formulas might be to set it to be equal to another resistance, eg '''default="(impact)"'''.
* Other keys reference the '''name=''' attribute of a defined movetype. For example, 'smallfoot=50' will set the resistance to 50 for the smallfoot movement type. Formulas can also be used here, for example 'smallfoot=(impact)'.

''Note:'' The '''default=''' key and other keys are handled slightly differently. A '''default=''' value will never override an explicitly specified value either in the same '''[resistance_defaults]''' tag or in a '''[movetype]''' definition, but other keys always take priority over values specified in a '''[movetype]''' definition.

{{DevFeature1.15|9}} The formulas can now access other parts of the movetype, for example "(resistance.arcane)" or "(movement_costs.flat)". For [resistance_defaults], "(arcane)" is shorthand for, and equivalent to, "(resistance.arcane)". See the documentation in the [terrain_defaults] section for more details about this.

=== [terrain_defaults] ===

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.11 ([https://github.com/wesnoth/wesnoth/issues/5308 issue #5308])

The '''[terrain_defaults]''' tag allows you to add costs and defenses for custom terrain types to already-defined movetypes (such as core movetypes).
* '''id''': The '''id=''' attribute of the terrain type you want to apply cost and defense defaults for.
* Subtags are used to specify the values using the same syntax as [resistance_defaults] - an optional default key, and subsequent keys which are movetype names. As with [resistance_defaults], you can use [[Wesnoth Formula Language|formulas]] if you enclose them in parentheses (but with no preceding dollar sign <code>$</code> or whitespace).
* Short names for the subtags are '''[movement]''', '''[jamming]''', '''[vision]''', and '''[defense]'''.
* Long names for the subtags are '''[movement_costs]''', '''[vision_costs]''', '''[jamming_costs]''', and '''[defense]'''.

1.14.16 and 1.15.11 recognise both the short and long names above. 1.15.9 and 1.15.10 only recognised the long names, and all other prior versions only recognised the short names.

{{DevFeature1.14|16}} {{DevFeature1.15|9}} The formulas can now access other parts of the movetype, for example '''(resistance.arcane)''' or '''(movement_costs.swamp_water)'''. Simply using '''(swamp_water)''' is shorthand for the value in whichever subtag is being patched. Formulas only recognise the long names.

The '''[terrain_defaults]''' tags are processed before any calculations of mixed terrains happen, and can only access the values for the basic terrain types. It's not useful to set a value for a mixed terrain type, as the calculations of mixed terrains' values decompose the mixed terrain to its base terrains before calculating the result, thus ignoring any patched values for mixed terrains.

Setting a '''default=''' value for '''[vision_costs]''' or '''[jamming_costs]''' means that that value will be used instead of falling back to using the movement_costs for calculating vision. For this reason, it's likely that '''default=''' should only be used when patching the '''[movement_costs]''' and '''[defense]''', not for vision or jamming.

A formula may use data added in a previous '''[terrain_defaults]'''. However, relying on data in the same '''[terrain_defaults]''' that creates or changes it is unsupported, because no guarantee is made of the order in which the subtags are processed.

While '''[terrain_defaults]''' formulas can use resistances, and '''[resistance_defaults]''' formulas can use movement costs, no guarantee is made of whether '''[terrain_defaults]''' tags will be processed before or after '''[resistance_defaults]''' tags. Therefore, formulas should only use base terrains and not rely on data added by the other kind of movetype-patching tag.

=== [hide_help] ===

The '''[hide_help]''' tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.
* '''type''': list of unit types.
* '''race''': list of races. Equivalent to all unit types of these races.
* '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
* '''all''': 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])
* '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
<syntaxhighlight lang=wml>
[hide_help]
all=yes
[not]
type=Yeti
race=human
[not]
type_adv_tree=Mage
[/not]
[/not]
[/hide_help]
</syntaxhighlight>

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EffectWML

2025-12-15T21:22:05Z

Shiki: abilities_list

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaAPI/wesnoth#wesnoth.effects]]. Some examples can be seen in [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/World_Conquest/lua/game_mechanics/effects.lua World Conquest].

[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''[remove_specials]''': {{DevFeature1.19|6}} remove the listed specials. Use [[StandardAbilityFilter]], special removed if matches. This tag is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''set_alignment''': {{DevFeature1.19|5}} Use for this attack an alignment of '''lawful''', '''neutral''', '''chaotic''' or '''liminal'''. It will be independent of the unit's alignment. Even if the unit's alignment changes, this attack will continue to use the alignment specified here.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
** '''set_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''set_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''set''': the new amount of the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''set_total''': will set the unit's max HP to the specified value.
** '''violate_maximum''': if the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''abilities_list''': {{DevFeature1.19|18}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this effect as if their full definition was included in '''[abilities]'''. Example: ''abilities=heals_8,regenerates''.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

== Examples ==
=== Effect: apply_to = new_animation ===
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y=1,5
[/filter]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]
</syntaxhighlight>
If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y=1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable=stored_unit
[/store_unit]
[set_variables]
name=stored_unit.modifications.object
[value]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable=stored_unit
[/unstore_unit]
[/event]
</syntaxhighlight>

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

UnitTypeWML

2025-12-01T05:26:49Z

Shiki: /* Attacks */ reword attack alignment

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version <b>1.14.3</b>.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.<br/>WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.<br/>{{DevFeature1.17|26}} canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in [https://github.com/wesnoth/wesnoth/pull/8375 8375].
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:
** ''scout'': Fast, mobile unit meant for exploration and village grabbing.
** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.
** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.
** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.
** ''healer'': Specialty 'heals' or 'cures'.
:Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''specials_list''': {{DevFeature1.19|17}} A comma-separated list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]], these will be added to this attack as if their full definition was included in '''[weapon_specials]'''. Example: ''weapon_specials=plague,magical''.
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} decouples the attack's alignment from the unit's alignment. One of ''lawful'', ''neutral'', ''chaotic'', ''liminal'' (See [[TimeWML]]). If unspecified, the unit alignment is used. Only useful for units with multiple attacks, otherwise you can change the unit alignment instead.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]
* '''abilities_list''': {{DevFeature1.19|17}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this unit type as if their full definition was included in '''[abilities]'''. Example: ''abilities=heals_8,regenerates''.

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities|WML Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

EffectWML

2025-11-30T14:47:16Z

Shiki: document set_alignment

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaAPI/wesnoth#wesnoth.effects]]. Some examples can be seen in [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/World_Conquest/lua/game_mechanics/effects.lua World Conquest].

[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''[remove_specials]''': {{DevFeature1.19|6}} remove the listed specials. Use [[StandardAbilityFilter]], special removed if matches. This tag is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''set_alignment''': {{DevFeature1.19|5}} Use for this attack an alignment of '''lawful''', '''neutral''', '''chaotic''' or '''liminal'''. It will be independent of the unit's alignment. Even if the unit's alignment changes, this attack will continue to use the alignment specified here.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
** '''set_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''set_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''set''': the new amount of the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''set_total''': will set the unit's max HP to the specified value.
** '''violate_maximum''': if the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''abilities''': {{DevFeature1.19|17}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this effect as if their full definition was included in '''[abilities]'''. Example: ''abilities=heals_8,regenerates''.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

== Examples ==
=== Effect: apply_to = new_animation ===
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y=1,5
[/filter]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]
</syntaxhighlight>
If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y=1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable=stored_unit
[/store_unit]
[set_variables]
name=stored_unit.modifications.object
[value]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable=stored_unit
[/unstore_unit]
[/event]
</syntaxhighlight>

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

EffectWML

2025-06-24T14:42:29Z

Shiki: /* Examples */ use syntax highlighting

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaAPI/wesnoth#wesnoth.effects]]. Some examples can be seen in [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/World_Conquest/lua/game_mechanics/effects.lua World Conquest].

[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''[remove_specials]''': {{DevFeature1.19|6}} remove the listed specials. Use [[StandardAbilityFilter]], special removed if matches. This tag is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
** '''set_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''set_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''set''': the new amount of the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''set_total''': will set the unit's max HP to the specified value.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

== Examples ==
=== Effect: apply_to = new_animation ===
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y=1,5
[/filter]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]
</syntaxhighlight>
If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
<syntaxhighlight lang='wml'>
[event]
name=moveto
[filter]
x,y=1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable=stored_unit
[/store_unit]
[set_variables]
name=stored_unit.modifications.object
[value]
[effect]
apply_to=new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable=stored_unit
[/unstore_unit]
[/event]
</syntaxhighlight>

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

LuaAPI/gui

2025-06-02T10:07:54Z

Shiki: change formatting

{{DevFeature1.15|0}}

== Submodules ==
=== gui.widget ===

A [[LuaAPI/gui/widget|submodule]] containing functions for working with widgets in custom dialogs.

== Functions ==
=== gui.add_widget_definition ===

* '''gui.add_widget_definition'''(''widget_type'', ''definition_id'', ''wml_content'')

Creates a new WML widget definition for the specified widget type, which can be referenced from dialog WML in the '''definition''' key.

=== gui.get_user_choice ===

* '''gui.get_user_choice'''(''attributes'', ''options'')

Shows a message dialog (like the one used by the <tt>[[InterfaceActionsWML#.5Bmessage.5D|[message]]]</tt> tag) with a series of options and returns the index (1-based) of the chosen option, which can be stored as a Lua variable.

'''IMPORTANT NOTE: this function is broken in Wesnoth 1.16.0 and 1.16.1.''' If you wish to use it, you should also use wesnoth.current_version to check that your code is being run on Wesnoth 1.16.2 or higher. Alternatively, you may try using [[#gui.show_narration|gui.show_narration]] instead, which has a similar function but a wider range of features.

The first argument is a table of attributes which are directly passed to the underlying <tt>[message]</tt> tag.

The second argument is a table of options, which are used to construct a series of underlying <tt>[option]</tt> tags. Most Lua data types are supported, but a few aren't:
* If the option is a ''table'' or a ''WML table'', these fields are supported:
** ''image'': icon shown in the first column;
** ''label'': text shown in the second column;
** ''description'': text shown in the third column (''message'' is also supported as an alias);
** ''default'': whether this is option is the one selected when the dialog is shown (boolean).
* If the option can be cast to a string (''strings'', ''translatable strings'', ''numbers'', ''booleans''), it is used for the content of the description field, which means that the first two columns will be empty.
* Otherwise, it raises an "invalid data type" error.

Example taken from the test scenario (if not used in an event then change the speaker):

<syntaxhighlight lang='lua'>
local result = gui.get_user_choice(
{ speaker = "unit", message = "Pick your poison" },
{ { image = "items/potion-red.png",
label = "Something red",
description = "Take a sip and enjoy" },
{ image = "items/potion-blue.png",
label = "Nice blue",
description = "Surely you’ll like that one",
default = true },
{ image = "items/potion-yellow.png",
label = "<span color='yellow'>Oh noes yellow</span>",
description = "Oh I’m sure you’ll love that one" },
{ image = "scenery/well.png",
label = "A nice well",
description = "Grab a bucket and fetch some water" },
{ image = "items/holy-water.png",
label = "Oh nice bottle",
description = "Feel the divinity" },
-- Should have an empty first column and a second column on two lines.
{ label = "Well a nice and black drink.\nToo dark too see?",
description = "Take a sip and pass the bottle along" }
})
wesnoth.interface.add_chat_message(string.format("User selected choice %d.", result))
</syntaxhighlight>

=== gui.show_dialog ===

* '''gui.show_dialog'''(''dialog definition'', ''preshow'', ''postshow'') → ''retval''

Displays a dialog box described by a WML table and returns an integer
* if the dialog was dismissed by a button click, the integer value associated to the button via the '''return_value''' keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the '''[resolution]''' section of a GUI window as described in [[GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in GUIToolkit page's [[GUIToolkit#Layout|Layout]] section and [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].) For an overview of the GUI system, see [[GUIToolkit]].

Two optional functions can be passed as second and third arguments; the function passed as ''preshow'' argument is called just before the dialog is shown; the second function (argument ''postshow'') is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions take a single parameter, which is the [[LuaAPI/types/widget|widget userdata]] representing the window.

For in-game dialogs that offer the player a choice and/or can change the game state, this function should be called in conjunction with [[LuaAPI/wesnoth/sync#evaluate_single|wesnoth.sync.evaluate_single]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client. Though this is especially important in multiplayer scenarios, failing to do it in a single-player scenario will cause the replay to break, so it should be done in either case.

See [[LuaAPI/gui/example|here]] for a fully-working example of a custom dialog.

=== gui.show_help ===

* '''gui.show_help'''([''topic''])

Show the in-game help, optionally opening a specified topic directly.

=== gui.show_inspector ===

* {{LuaGameOnly}} '''gui.show_inspector'''()

Show the gamestate inspector.

=== gui.show_lua_console ===

* '''gui.show_lua_console'''()

Shows the Lua console. This works even if debug mode is not enabled.

=== gui.show_menu ===

* '''gui.show_menu'''(''items'', [''initial''], [''markup'']) → ''index''

Shows a popup menu onscreen at the current mouse location. This could be used for example to produce a sort of submenu in a <tt>[set_menu_item]</tt>. The items are specified as a Lua array of tables, each of which supports the following keys:

* ''icon'': An icon to display in the leftmost column of the menu.
* ''image'': An image to display in the main column of the menu. If this is present, ''label'' is ignored.
* ''label'': A label to display in the main column of the menu.
* ''details'': A secondary label to display in the right column of the menu.
* ''tooltip'': Text to display when mousing over this option.

The ''initial'' argument must be a valid index into the ''items'' array, or 0 to indicate that no element is initially selected (which is the default but typically not what you want).

The ''markup'' argument specifies whether Pango markup will be parsed in the menuitems. It defaults to false.

The ''initial'' and ''markup'' arguments can be passed in either order; the game will understand which is meant based on the type of the argument.

This function returns the index of the selected item. If the user cancelled by clicking outside the menu's boundary, 0 is returned.

=== gui.show_narration ===

* '''gui.show_narration'''(''attributes'', [''options'', [''text_input_attributes'']]) → ''result_code'', [''entered_text'']

Shows a message dialog, of the type used by the <tt>[message]</tt> ActionWML tag. Unlike the <tt>[message]</tt> tag, this is unsynced; if you need it synced, you must do it yourself. The first argument is a table describing the dialog with the following keys:

* ''title'' - The title to show on the message. For example, the speaker's name.
* ''message'' - The message content.
* ''portrait'' - An image to show along with the message. By default, no image is shown.
* ''left_side'' - The default is true; set to false to show the image on the right.
* ''mirror'' - If true, the image will be flipped horizontally.

The second argument is a list of options as a Lua array. Each option is either a (possibly-translatable) string or a config with [[DescriptionWML#WML_Format|DescriptionWML]] keys. The array itself can also have an optional '''default''' key which if present should be the index of the initially selected option (useful if you don't need full DescriptionWML but want to set a default). If present it overrides any defaults set in individual options.

The third argument is a table describing the text input field with the following keys:

* ''label'' - A label to show to the left of the text field.
* ''text'' - Initial contents of the text field.
* ''max_length'' - Maximum input length in characters (defaults to 256).

You need at least one key for the text input to be shown. Both the second and third arguments are optional, but if you want text input with no options, you must pass nil for the second parameter.

This function returns one or two values. The first value returned is the numeric result of the dialog:

* If there are no options and no text input, the result is -2 if the user pressed Escape, or -1 if they closed by clicking or pressing Space.
* If there are options, the result is the index of the option chosen (starting from 1).
* If there is text input but no options, the first return value is 0.

The second value returned is the text entered, if there was text input. Otherwise there is no second value (it is nil).

Example:

<syntaxhighlight lang='lua'>
gui.show_narration({
title = "Make your choice:",
message = "Select an option and enter some text.",
portrait = "wesnoth-icon.png",
}, {
"The first choice is always the best!",
"Pick me! Second choices are better!",
"You know you want the third option!",
}, {
label = "Text:",
text = "?",
max_length = 16
})
</syntaxhighlight>

(You don't have to format it like that, of course.)

=== gui.show_popup ===

* '''gui.show_popup'''(''title'', ''message'', [''image''])

Shows a simple popup dialog in the centre of the screen. Takes three arguments, which in order are:

# A title string for the dialog
# The message content for the dialog.
# An image to show.

Both the title and the message support Pango markup. The image is optional.

=== gui.show_prompt ===

* '''gui.show_prompt'''(''title'', ''message'', [''button''], [''markup'']) → ''result''
* '''gui.confirm'''([''title'',] ''message'') → ''result''
* '''gui.alert'''([''title''], ''message'')

Shows a standard message box onscreen (similar to the quit confirmation message, for example). The button can be any arbitrary potentially-translatable string (in which case, there will be one button with that label), or it can be one of the following special string values:

* ''ok'' or nil: A single OK button; this is the default
* ''cancel'': A single Cancel button
* ''close'': A single Close button
* ''ok_cancel'': Two buttons labelled OK and Cancel
* ''yes_no'': Two buttons labelled Yes and No
* an empty string: No buttons; the dialog automatically closes after a few seconds

The alert and confirm functions are simpler wrappers for this function, using a single OK button and a pair of Yes/No buttons, respectively. Both confirm and show_prompt return false if No or Cancel was clicked, and true otherwise. The alert function returns nothing.

=== gui.show_recruit_dialog ===

{{DevFeature1.19|8}}

* {{LuaGameOnly}} '''gui.show_recruit_dialog'''(''unit_types_list'', [''unit_dialog_options'']) → ''unit_type''

Shows the recruit dialog with the given list of unit types and options. The first argument is a table of [[LuaAPI/types#Unit_Type|unit types]]. The second argument is an optional table that can be used to set various properties of the dialog shown. These are:

* ''title'': the title of the dialog.
* ''ok_label'': caption of the button with id "ok".
* ''cancel_label'': caption of the button with id "cancel".
* ''help_topic'': the help topic that is to be opened when the '?' button is clicked.
* ''show_headers'': (boolean) whether to show column headers in the main list of the dialog. By default, the headers are not shown.

=== gui.show_recall_dialog ===

{{DevFeature1.19|8}}

* {{LuaGameOnly}} '''gui.show_recall_dialog'''(''units_list'', [''unit_dialog_options'']) → ''unit''

Shows the recall dialog with the given list of units and options. The first argument is a table of [[LuaAPI/types/unit|units]]. The second argument is an optional table that can be used to set various properties of the dialog shown. These are:

* ''title'': the title of the dialog.
* ''ok_label'': caption of the button with id "ok".
* ''cancel_label'': caption of the button with id "cancel".
* ''help_topic'': the help topic that is to be opened when the '?' button is clicked.
* ''show_headers'': (boolean) whether to show column headers in the main list of the dialog. By default, the headers are shown.

=== gui.show_story ===

* '''gui.show_story'''(''story_config'', ''default_title'')

Shows the storyscreen. The passed config is identical to the contents of [[IntroWML|[story]]]. The second parameter is the default title used if a part does not specify one — unlike intro storyscreens, a Lua-invoked one does not default to the scenario name.

=== gui.switch_theme ===

{{DevFeature1.19|4}}

* '''gui.switch_theme'''(''theme_id'')

Switch to the GUI2 theme with id ''theme_id''. Can only be used inside a scenario and does not replace the UI Theme selected by Preferences. The UI reverts to the theme selected in Preferences after exiting the in-game window, for example, by using the menu or by winning or losing a campaign.

[[Category:Lua Reference]]

LuaAPI/gui

2025-06-02T10:05:27Z

Shiki: /* gui.show_recall_dialog */

{{DevFeature1.15|0}}

== Submodules ==
=== gui.widget ===

A [[LuaAPI/gui/widget|submodule]] containing functions for working with widgets in custom dialogs.

== Functions ==
=== gui.add_widget_definition ===

* '''gui.add_widget_definition'''(''widget_type'', ''definition_id'', ''wml_content'')

Creates a new WML widget definition for the specified widget type, which can be referenced from dialog WML in the '''definition''' key.

=== gui.get_user_choice ===

* '''gui.get_user_choice'''(''attributes'', ''options'')

Shows a message dialog (like the one used by the <tt>[[InterfaceActionsWML#.5Bmessage.5D|[message]]]</tt> tag) with a series of options and returns the index (1-based) of the chosen option, which can be stored as a Lua variable.

'''IMPORTANT NOTE: this function is broken in Wesnoth 1.16.0 and 1.16.1.''' If you wish to use it, you should also use wesnoth.current_version to check that your code is being run on Wesnoth 1.16.2 or higher. Alternatively, you may try using [[#gui.show_narration|gui.show_narration]] instead, which has a similar function but a wider range of features.

The first argument is a table of attributes which are directly passed to the underlying <tt>[message]</tt> tag.

The second argument is a table of options, which are used to construct a series of underlying <tt>[option]</tt> tags. Most Lua data types are supported, but a few aren't:
* If the option is a ''table'' or a ''WML table'', these fields are supported:
** ''image'': icon shown in the first column;
** ''label'': text shown in the second column;
** ''description'': text shown in the third column (''message'' is also supported as an alias);
** ''default'': whether this is option is the one selected when the dialog is shown (boolean).
* If the option can be cast to a string (''strings'', ''translatable strings'', ''numbers'', ''booleans''), it is used for the content of the description field, which means that the first two columns will be empty.
* Otherwise, it raises an "invalid data type" error.

Example taken from the test scenario (if not used in an event then change the speaker):

<syntaxhighlight lang='lua'>
local result = gui.get_user_choice(
{ speaker = "unit", message = "Pick your poison" },
{ { image = "items/potion-red.png",
label = "Something red",
description = "Take a sip and enjoy" },
{ image = "items/potion-blue.png",
label = "Nice blue",
description = "Surely you’ll like that one",
default = true },
{ image = "items/potion-yellow.png",
label = "<span color='yellow'>Oh noes yellow</span>",
description = "Oh I’m sure you’ll love that one" },
{ image = "scenery/well.png",
label = "A nice well",
description = "Grab a bucket and fetch some water" },
{ image = "items/holy-water.png",
label = "Oh nice bottle",
description = "Feel the divinity" },
-- Should have an empty first column and a second column on two lines.
{ label = "Well a nice and black drink.\nToo dark too see?",
description = "Take a sip and pass the bottle along" }
})
wesnoth.interface.add_chat_message(string.format("User selected choice %d.", result))
</syntaxhighlight>

=== gui.show_dialog ===

* '''gui.show_dialog'''(''dialog definition'', ''preshow'', ''postshow'') → ''retval''

Displays a dialog box described by a WML table and returns an integer
* if the dialog was dismissed by a button click, the integer value associated to the button via the '''return_value''' keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the '''[resolution]''' section of a GUI window as described in [[GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in GUIToolkit page's [[GUIToolkit#Layout|Layout]] section and [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].) For an overview of the GUI system, see [[GUIToolkit]].

Two optional functions can be passed as second and third arguments; the function passed as ''preshow'' argument is called just before the dialog is shown; the second function (argument ''postshow'') is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions take a single parameter, which is the [[LuaAPI/types/widget|widget userdata]] representing the window.

For in-game dialogs that offer the player a choice and/or can change the game state, this function should be called in conjunction with [[LuaAPI/wesnoth/sync#evaluate_single|wesnoth.sync.evaluate_single]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client. Though this is especially important in multiplayer scenarios, failing to do it in a single-player scenario will cause the replay to break, so it should be done in either case.

See [[LuaAPI/gui/example|here]] for a fully-working example of a custom dialog.

=== gui.show_help ===

* '''gui.show_help'''([''topic''])

Show the in-game help, optionally opening a specified topic directly.

=== gui.show_inspector ===

* {{LuaGameOnly}} '''gui.show_inspector'''()

Show the gamestate inspector.

=== gui.show_lua_console ===

* '''gui.show_lua_console'''()

Shows the Lua console. This works even if debug mode is not enabled.

=== gui.show_menu ===

* '''gui.show_menu'''(''items'', [''initial''], [''markup'']) → ''index''

Shows a popup menu onscreen at the current mouse location. This could be used for example to produce a sort of submenu in a <tt>[set_menu_item]</tt>. The items are specified as a Lua array of tables, each of which supports the following keys:

* ''icon'': An icon to display in the leftmost column of the menu.
* ''image'': An image to display in the main column of the menu. If this is present, ''label'' is ignored.
* ''label'': A label to display in the main column of the menu.
* ''details'': A secondary label to display in the right column of the menu.
* ''tooltip'': Text to display when mousing over this option.

The ''initial'' argument must be a valid index into the ''items'' array, or 0 to indicate that no element is initially selected (which is the default but typically not what you want).

The ''markup'' argument specifies whether Pango markup will be parsed in the menuitems. It defaults to false.

The ''initial'' and ''markup'' arguments can be passed in either order; the game will understand which is meant based on the type of the argument.

This function returns the index of the selected item. If the user cancelled by clicking outside the menu's boundary, 0 is returned.

=== gui.show_narration ===

* '''gui.show_narration'''(''attributes'', [''options'', [''text_input_attributes'']]) → ''result_code'', [''entered_text'']

Shows a message dialog, of the type used by the <tt>[message]</tt> ActionWML tag. Unlike the <tt>[message]</tt> tag, this is unsynced; if you need it synced, you must do it yourself. The first argument is a table describing the dialog with the following keys:

* ''title'' - The title to show on the message. For example, the speaker's name.
* ''message'' - The message content.
* ''portrait'' - An image to show along with the message. By default, no image is shown.
* ''left_side'' - The default is true; set to false to show the image on the right.
* ''mirror'' - If true, the image will be flipped horizontally.

The second argument is a list of options as a Lua array. Each option is either a (possibly-translatable) string or a config with [[DescriptionWML#WML_Format|DescriptionWML]] keys. The array itself can also have an optional '''default''' key which if present should be the index of the initially selected option (useful if you don't need full DescriptionWML but want to set a default). If present it overrides any defaults set in individual options.

The third argument is a table describing the text input field with the following keys:

* ''label'' - A label to show to the left of the text field.
* ''text'' - Initial contents of the text field.
* ''max_length'' - Maximum input length in characters (defaults to 256).

You need at least one key for the text input to be shown. Both the second and third arguments are optional, but if you want text input with no options, you must pass nil for the second parameter.

This function returns one or two values. The first value returned is the numeric result of the dialog:

* If there are no options and no text input, the result is -2 if the user pressed Escape, or -1 if they closed by clicking or pressing Space.
* If there are options, the result is the index of the option chosen (starting from 1).
* If there is text input but no options, the first return value is 0.

The second value returned is the text entered, if there was text input. Otherwise there is no second value (it is nil).

Example:

<syntaxhighlight lang='lua'>
gui.show_narration({
title = "Make your choice:",
message = "Select an option and enter some text.",
portrait = "wesnoth-icon.png",
}, {
"The first choice is always the best!",
"Pick me! Second choices are better!",
"You know you want the third option!",
}, {
label = "Text:",
text = "?",
max_length = 16
})
</syntaxhighlight>

(You don't have to format it like that, of course.)

=== gui.show_popup ===

* '''gui.show_popup'''(''title'', ''message'', [''image''])

Shows a simple popup dialog in the centre of the screen. Takes three arguments, which in order are:

# A title string for the dialog
# The message content for the dialog.
# An image to show.

Both the title and the message support Pango markup. The image is optional.

=== gui.show_prompt ===

* '''gui.show_prompt'''(''title'', ''message'', [''button''], [''markup'']) → ''result''
* '''gui.confirm'''([''title'',] ''message'') → ''result''
* '''gui.alert'''([''title''], ''message'')

Shows a standard message box onscreen (similar to the quit confirmation message, for example). The button can be any arbitrary potentially-translatable string (in which case, there will be one button with that label), or it can be one of the following special string values:

* ''ok'' or nil: A single OK button; this is the default
* ''cancel'': A single Cancel button
* ''close'': A single Close button
* ''ok_cancel'': Two buttons labelled OK and Cancel
* ''yes_no'': Two buttons labelled Yes and No
* an empty string: No buttons; the dialog automatically closes after a few seconds

The alert and confirm functions are simpler wrappers for this function, using a single OK button and a pair of Yes/No buttons, respectively. Both confirm and show_prompt return false if No or Cancel was clicked, and true otherwise. The alert function returns nothing.

=== gui.show_recruit_dialog ===

{{DevFeature1.19|8}}

* {{LuaGameOnly}} '''gui.show_recruit_dialog'''(''unit_types_list'', [''unit_dialog_options'']) → ''unit_type''

Shows the recruit dialog with the given list of unit types and options. The first argument is a table of [[LuaAPI/types#Unit_Type|unit types]]. The second argument is an optional table that can be used to set various properties of the dialog shown. These are:

* '''title''': the title of the dialog.
* '''ok_label''': caption of the button with id "ok".
* '''cancel_label''': caption of the button with id "cancel".
* '''help_topic''': the help topic that is to be opened when the '?' button is clicked.
* '''show_headers''': (boolean) whether to show column headers in the main list of the dialog. By default, the headers are not shown.

=== gui.show_recall_dialog ===

{{DevFeature1.19|8}}

* {{LuaGameOnly}} '''gui.show_recall_dialog'''(''units_list'', [''unit_dialog_options'']) → ''unit''

Shows the recall dialog with the given list of units and options. The first argument is a table of [[LuaAPI/types/unit|units]]. The second argument is an optional table that can be used to set various properties of the dialog shown. These are:

* '''title''': the title of the dialog.
* '''ok_label''': caption of the button with id "ok".
* '''cancel_label''': caption of the button with id "cancel".
* '''help_topic''': the help topic that is to be opened when the '?' button is clicked.
* '''show_headers''': (boolean) whether to show column headers in the main list of the dialog. By default, the headers are shown.

=== gui.show_story ===

* '''gui.show_story'''(''story_config'', ''default_title'')

Shows the storyscreen. The passed config is identical to the contents of [[IntroWML|[story]]]. The second parameter is the default title used if a part does not specify one — unlike intro storyscreens, a Lua-invoked one does not default to the scenario name.

=== gui.switch_theme ===

{{DevFeature1.19|4}}

* '''gui.switch_theme'''(''theme_id'')

Switch to the GUI2 theme with id ''theme_id''. Can only be used inside a scenario and does not replace the UI Theme selected by Preferences. The UI reverts to the theme selected in Preferences after exiting the in-game window, for example, by using the menu or by winning or losing a campaign.

[[Category:Lua Reference]]

LuaAPI/gui

2025-06-02T10:04:37Z

Shiki: show return value

{{DevFeature1.15|0}}

== Submodules ==
=== gui.widget ===

A [[LuaAPI/gui/widget|submodule]] containing functions for working with widgets in custom dialogs.

== Functions ==
=== gui.add_widget_definition ===

* '''gui.add_widget_definition'''(''widget_type'', ''definition_id'', ''wml_content'')

Creates a new WML widget definition for the specified widget type, which can be referenced from dialog WML in the '''definition''' key.

=== gui.get_user_choice ===

* '''gui.get_user_choice'''(''attributes'', ''options'')

Shows a message dialog (like the one used by the <tt>[[InterfaceActionsWML#.5Bmessage.5D|[message]]]</tt> tag) with a series of options and returns the index (1-based) of the chosen option, which can be stored as a Lua variable.

'''IMPORTANT NOTE: this function is broken in Wesnoth 1.16.0 and 1.16.1.''' If you wish to use it, you should also use wesnoth.current_version to check that your code is being run on Wesnoth 1.16.2 or higher. Alternatively, you may try using [[#gui.show_narration|gui.show_narration]] instead, which has a similar function but a wider range of features.

The first argument is a table of attributes which are directly passed to the underlying <tt>[message]</tt> tag.

The second argument is a table of options, which are used to construct a series of underlying <tt>[option]</tt> tags. Most Lua data types are supported, but a few aren't:
* If the option is a ''table'' or a ''WML table'', these fields are supported:
** ''image'': icon shown in the first column;
** ''label'': text shown in the second column;
** ''description'': text shown in the third column (''message'' is also supported as an alias);
** ''default'': whether this is option is the one selected when the dialog is shown (boolean).
* If the option can be cast to a string (''strings'', ''translatable strings'', ''numbers'', ''booleans''), it is used for the content of the description field, which means that the first two columns will be empty.
* Otherwise, it raises an "invalid data type" error.

Example taken from the test scenario (if not used in an event then change the speaker):

<syntaxhighlight lang='lua'>
local result = gui.get_user_choice(
{ speaker = "unit", message = "Pick your poison" },
{ { image = "items/potion-red.png",
label = "Something red",
description = "Take a sip and enjoy" },
{ image = "items/potion-blue.png",
label = "Nice blue",
description = "Surely you’ll like that one",
default = true },
{ image = "items/potion-yellow.png",
label = "<span color='yellow'>Oh noes yellow</span>",
description = "Oh I’m sure you’ll love that one" },
{ image = "scenery/well.png",
label = "A nice well",
description = "Grab a bucket and fetch some water" },
{ image = "items/holy-water.png",
label = "Oh nice bottle",
description = "Feel the divinity" },
-- Should have an empty first column and a second column on two lines.
{ label = "Well a nice and black drink.\nToo dark too see?",
description = "Take a sip and pass the bottle along" }
})
wesnoth.interface.add_chat_message(string.format("User selected choice %d.", result))
</syntaxhighlight>

=== gui.show_dialog ===

* '''gui.show_dialog'''(''dialog definition'', ''preshow'', ''postshow'') → ''retval''

Displays a dialog box described by a WML table and returns an integer
* if the dialog was dismissed by a button click, the integer value associated to the button via the '''return_value''' keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the '''[resolution]''' section of a GUI window as described in [[GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in GUIToolkit page's [[GUIToolkit#Layout|Layout]] section and [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].) For an overview of the GUI system, see [[GUIToolkit]].

Two optional functions can be passed as second and third arguments; the function passed as ''preshow'' argument is called just before the dialog is shown; the second function (argument ''postshow'') is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions take a single parameter, which is the [[LuaAPI/types/widget|widget userdata]] representing the window.

For in-game dialogs that offer the player a choice and/or can change the game state, this function should be called in conjunction with [[LuaAPI/wesnoth/sync#evaluate_single|wesnoth.sync.evaluate_single]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client. Though this is especially important in multiplayer scenarios, failing to do it in a single-player scenario will cause the replay to break, so it should be done in either case.

See [[LuaAPI/gui/example|here]] for a fully-working example of a custom dialog.

=== gui.show_help ===

* '''gui.show_help'''([''topic''])

Show the in-game help, optionally opening a specified topic directly.

=== gui.show_inspector ===

* {{LuaGameOnly}} '''gui.show_inspector'''()

Show the gamestate inspector.

=== gui.show_lua_console ===

* '''gui.show_lua_console'''()

Shows the Lua console. This works even if debug mode is not enabled.

=== gui.show_menu ===

* '''gui.show_menu'''(''items'', [''initial''], [''markup'']) → ''index''

Shows a popup menu onscreen at the current mouse location. This could be used for example to produce a sort of submenu in a <tt>[set_menu_item]</tt>. The items are specified as a Lua array of tables, each of which supports the following keys:

* ''icon'': An icon to display in the leftmost column of the menu.
* ''image'': An image to display in the main column of the menu. If this is present, ''label'' is ignored.
* ''label'': A label to display in the main column of the menu.
* ''details'': A secondary label to display in the right column of the menu.
* ''tooltip'': Text to display when mousing over this option.

The ''initial'' argument must be a valid index into the ''items'' array, or 0 to indicate that no element is initially selected (which is the default but typically not what you want).

The ''markup'' argument specifies whether Pango markup will be parsed in the menuitems. It defaults to false.

The ''initial'' and ''markup'' arguments can be passed in either order; the game will understand which is meant based on the type of the argument.

This function returns the index of the selected item. If the user cancelled by clicking outside the menu's boundary, 0 is returned.

=== gui.show_narration ===

* '''gui.show_narration'''(''attributes'', [''options'', [''text_input_attributes'']]) → ''result_code'', [''entered_text'']

Shows a message dialog, of the type used by the <tt>[message]</tt> ActionWML tag. Unlike the <tt>[message]</tt> tag, this is unsynced; if you need it synced, you must do it yourself. The first argument is a table describing the dialog with the following keys:

* ''title'' - The title to show on the message. For example, the speaker's name.
* ''message'' - The message content.
* ''portrait'' - An image to show along with the message. By default, no image is shown.
* ''left_side'' - The default is true; set to false to show the image on the right.
* ''mirror'' - If true, the image will be flipped horizontally.

The second argument is a list of options as a Lua array. Each option is either a (possibly-translatable) string or a config with [[DescriptionWML#WML_Format|DescriptionWML]] keys. The array itself can also have an optional '''default''' key which if present should be the index of the initially selected option (useful if you don't need full DescriptionWML but want to set a default). If present it overrides any defaults set in individual options.

The third argument is a table describing the text input field with the following keys:

* ''label'' - A label to show to the left of the text field.
* ''text'' - Initial contents of the text field.
* ''max_length'' - Maximum input length in characters (defaults to 256).

You need at least one key for the text input to be shown. Both the second and third arguments are optional, but if you want text input with no options, you must pass nil for the second parameter.

This function returns one or two values. The first value returned is the numeric result of the dialog:

* If there are no options and no text input, the result is -2 if the user pressed Escape, or -1 if they closed by clicking or pressing Space.
* If there are options, the result is the index of the option chosen (starting from 1).
* If there is text input but no options, the first return value is 0.

The second value returned is the text entered, if there was text input. Otherwise there is no second value (it is nil).

Example:

<syntaxhighlight lang='lua'>
gui.show_narration({
title = "Make your choice:",
message = "Select an option and enter some text.",
portrait = "wesnoth-icon.png",
}, {
"The first choice is always the best!",
"Pick me! Second choices are better!",
"You know you want the third option!",
}, {
label = "Text:",
text = "?",
max_length = 16
})
</syntaxhighlight>

(You don't have to format it like that, of course.)

=== gui.show_popup ===

* '''gui.show_popup'''(''title'', ''message'', [''image''])

Shows a simple popup dialog in the centre of the screen. Takes three arguments, which in order are:

# A title string for the dialog
# The message content for the dialog.
# An image to show.

Both the title and the message support Pango markup. The image is optional.

=== gui.show_prompt ===

* '''gui.show_prompt'''(''title'', ''message'', [''button''], [''markup'']) → ''result''
* '''gui.confirm'''([''title'',] ''message'') → ''result''
* '''gui.alert'''([''title''], ''message'')

Shows a standard message box onscreen (similar to the quit confirmation message, for example). The button can be any arbitrary potentially-translatable string (in which case, there will be one button with that label), or it can be one of the following special string values:

* ''ok'' or nil: A single OK button; this is the default
* ''cancel'': A single Cancel button
* ''close'': A single Close button
* ''ok_cancel'': Two buttons labelled OK and Cancel
* ''yes_no'': Two buttons labelled Yes and No
* an empty string: No buttons; the dialog automatically closes after a few seconds

The alert and confirm functions are simpler wrappers for this function, using a single OK button and a pair of Yes/No buttons, respectively. Both confirm and show_prompt return false if No or Cancel was clicked, and true otherwise. The alert function returns nothing.

=== gui.show_recruit_dialog ===

{{DevFeature1.19|8}}

* {{LuaGameOnly}} '''gui.show_recruit_dialog'''(''unit_types_list'', [''unit_dialog_options'']) → ''unit_type''

Shows the recruit dialog with the given list of unit types and options. The first argument is a table of [[LuaAPI/types#Unit_Type|unit types]]. The second argument is an optional table that can be used to set various properties of the dialog shown. These are:

* '''title''': the title of the dialog.
* '''ok_label''': caption of the button with id "ok".
* '''cancel_label''': caption of the button with id "cancel".
* '''help_topic''': the help topic that is to be opened when the '?' button is clicked.
* '''show_headers''': (boolean) whether to show column headers in the main list of the dialog. By default, the headers are not shown.

=== gui.show_recall_dialog ===

{{DevFeature1.19|8}}

* {{LuaGameOnly}} '''gui.show_recall_dialog'''(''units_list'', [''unit_dialog_options'']) → ''unit_type''

Shows the recall dialog with the given list of units and options. The first argument is a table of [[LuaAPI/types/unit|units]]. The second argument is an optional table that can be used to set various properties of the dialog shown. These are:

* '''title''': the title of the dialog.
* '''ok_label''': caption of the button with id "ok".
* '''cancel_label''': caption of the button with id "cancel".
* '''help_topic''': the help topic that is to be opened when the '?' button is clicked.
* '''show_headers''': (boolean) whether to show column headers in the main list of the dialog. By default, the headers are shown.

=== gui.show_story ===

* '''gui.show_story'''(''story_config'', ''default_title'')

Shows the storyscreen. The passed config is identical to the contents of [[IntroWML|[story]]]. The second parameter is the default title used if a part does not specify one — unlike intro storyscreens, a Lua-invoked one does not default to the scenario name.

=== gui.switch_theme ===

{{DevFeature1.19|4}}

* '''gui.switch_theme'''(''theme_id'')

Switch to the GUI2 theme with id ''theme_id''. Can only be used inside a scenario and does not replace the UI Theme selected by Preferences. The UI reverts to the theme selected in Preferences after exiting the in-game window, for example, by using the menu or by winning or losing a campaign.

[[Category:Lua Reference]]

EditorWML

2025-05-28T16:43:27Z

Shiki: /* Units */ switch to own [units] tag

{{WML Tags}}

Wesnoth's Map Editor allows configuration of certain aspects via the following WML. All save <b>[brush]</b> are free to be used be UMC content creators. All code within '''#ifdef EDITOR ... #endif''' blocks should be placed in your _main.cfg.

== The [brush] tag ==
Each brush tag defines one brush. (0,0) is the hotspot, that is, the brush is always moved so the mouse is over the brush's (0,0) coordinate. The following keys and tags are recognized:
* '''name''': name for the brush (will possibly show up in the tooltip for the brush)
* '''image''': icon for the brush to de displayed on the toolbar
* '''radius''': (int) include in the brushall hexes that are this or closer to the center of the brush, excluding the (0,0) point
* '''[relative]''': include in the brush a single hex with coordinates relative from the center of the brush
** '''x''': the relative x coordinate
** '''y''': the relative y coordinate
A brush that has neither a radius nor any [relative] hexes will be empty which is not desired and a warning or error is to be expected.

==The [editor_times] tag==
The editor_times tag defines a schedule (time-of-day) for the editor. Standard time of day macros can be used.
* '''[[TimeWML|[time]]]''' Time of day definitions
* '''id''': The identifier of the time schedule
* '''name''': The translatable name of the schedule

An example using Wesnoth default Time of Day schedule:

<syntaxhighlight lang=wml>
#ifdef EDITOR
[editor_times]
name= _ "Default"
id=default
{DEFAULT_SCHEDULE}
[/editor_times]
#endif
</syntaxhighlight>

==The [editor_music] tag==
This tag defines a music playlist for the editor. Standard music macros can be used here.
* '''[[MusicListWML|Music]]''': Playlist item definitions

Example of code to be put in _main.cfg from the add-on UMC Music Book 1:
<syntaxhighlight lang=wml>
#ifdef EDITOR

[binary_path]
path="data/add-ons/UMC_Music_Book_1"
[/binary_path]

[editor_music]

[music]
name=a3deap_DontFearTheReaper.ogg
append=yes
title="Don't Fear The Reaper"
[/music]
[music]
name=a3deap_GoForTheWorldAgain.ogg
append=yes
title="Go For The World Again"
[/music]
[music]
name=a3deap_HighInTheMountains.ogg
append=yes
title="High In The Mountains"
[/music]
[music]
name=a3deap_HoistTheColours.ogg
append=yes
title="Hoist The Colors"
[/music]
[music]
name=battlecry.ogg
append=yes
title="Battlecry"
[/music]
[music]
name=calm-before-storm.ogg
append=yes
title="Calm Before The Storm"
[/music]
[music]
name=gameplay06.ogg
append=yes
title="Gameplay06"
[/music]
[music]
name=snowfall.ogg
append=yes
title="Snowfall"
[/music]
[music]
name=tribal_war_song.ogg
append=yes
title="Tribal War Song"
[/music]

[/editor_music]
#endif
</syntaxhighlight>

==The [editor_group] tag ==
The editor_group tag defines a group of terrains displayed together on the terrain palette. Terrains must use a editor_group attribute from the list of ids specified in the editor_group tags. Custom terrains should be put in their own separate groups.
* '''id''': the unique id of this group. Duplicates are ignored.
* '''name''': a name for the group
* '''icon''': an icon for the group
* '''core''': whether this group is a "core" group. Non-core (UMC) groups are treated slightly differently by the editor -- a warning may be given to map authors, since maps using non-core terrains need special treatment in the scenario file to work properly. UMC groups should not define this attribute.

In order to get the editor to see custom terrains, you need to do something like the following:

<syntaxhighlight lang=wml>
#ifdef EDITOR
[binary_path]
path=data/campaigns/Under_the_Burning_Suns
[/binary_path]
[editor_group]
id=utbs
name= _ "Under the Burning Suns"
icon="group_custom"
[/editor_group]
{campaigns/Under_the_Burning_Suns/utils/terrain.cfg}
{campaigns/Under_the_Burning_Suns/utils/terrain_graphics.cfg}
#endif
</syntaxhighlight>

==The [item_group] tag==
The item_group tag defines a group of items displayed together in the items palette.
* '''id''': The unique id of the group.
* '''icon''': An icon to use for the group.
* '''name''': A name for the group.
* '''core''': Whether this is a core group. Should not be specified by UMC content.
* '''[item]''': Definition of the items in the group. See [[InterfaceActionsWML#.5Bitem.5D|[item]]].

<syntaxhighlight lang=wml>
#ifdef EDITOR
[item_group]
id=somegroup
name= _ "Some Group"
icon=icons/book.png
[item]
id=someitem
name= _ "Some Item"
image=scenary/fire1.png
halo=scenery/fire[1~8].png:100
[/item]
[/item_group]
#endif
</syntaxhighlight>

== Units ==

The following is a code example for allowing the use of units in the map editor - in this case for an add-on called Great_Legends_Era. The macros folder must be included if any of the units have weapon specials or abilities that make use of those macros.

<syntaxhighlight lang=wml>
#ifdef EDITOR
{~add-ons/Great_Legend_Era/macros}
[units]
{~add-ons/Great_Legend_Era/units}
{~add-ons/Great_Legend_Era/units/humans}
{~add-ons/Great_Legend_Era/units/trolls}
{~add-ons/Great_Legend_Era/units/elementals}
{~add-ons/Great_Legend_Era/units/knightmare}
{~add-ons/Great_Legend_Era/units/orcs}
{~add-ons/Great_Legend_Era/units/elves-desert}
{~add-ons/Great_Legend_Era/units/vampires}
{~add-ons/Great_Legend_Era/units/gargoyles}
{~add-ons/Great_Legend_Era/units/monsters}
[/units]
#endif
</syntaxhighlight>

[[Category: WML Reference]]

HelpWML

2025-04-25T21:52:52Z

Shiki: /* See Also */ link to help markup

{{WML Tags}}
== The toplevel [help] tag ==

The [help] tag describes the Wesnoth help system.
Each of the three subtags [toplevel], [section] and [topic] describe an element of the help system.

* {{anchor|toplevel|'''[toplevel]'''}}: The toplevel tag denotes sections and topics that should be shown immediately when the "Help" button is clicked on (see the "help" action, [[ThemeWML]]). The sections referenced within this tag are read recursively, including all subsections.
** '''sections''': a list of IDs of the sections to include recursively.
** '''topics''': a list of IDs of the topics to show as not being included in a section; i.e. top-level topics.
* {{anchor|section|'''[section]'''}}: The section tag describes a section in the help browser. A section contains subsections and/or topics.
** '''id''': is the unique ID for this section.
** '''title''': (translatable) is the title of the section. It is displayed in the left menu.
** '''sections''': is a list of IDs of the sections that should be this section's subsections.
** '''topics''': is a list of IDs of the topics that should be included in this section. Topics will be included in the order listed unless sorting is requested.
** '''generator''': provides the name of a function that will generate a list of topics and include them in this section. These topics will be included after topics listed on the '''topics''' key unless ''sort_topics'' is ''yes''.
** '''sort_topics''': specifies whether or not to list the topics sorted by title or in the order listed on the '''topics''' key. '''yes''' indicates fixed and generated topics should be sorted together by title. '''no''' indicates that topics should appear in the order listed with fixed topics appearing before generated topics. '''generated''' indicates that fixed topics should not be sorted and will be followed by generated topics sorted by the generator. The default is '''generated'''.
* {{anchor|topic|'''[topic]'''}}: The topic tag describes one topic, i.e, one help page. The keys that are meaningful in the topic tag:
** '''id''': is the unique ID for this topic.
** '''title''': (translatable) is the title of the topic. It is displayed in the left menu and as a header in the text area.
** '''text''': (translatable) is the contents of the topics. May contain markup described below.

== Help System Topic Markup ==

The markup that is allowed in the text key within a topic tag is in a WML-like markup language with angle brackets.

It consists of plain text, interrupted with markup tags. Between paired start and end tags (like '''<jump> ... </jump>''') you can give keys and values like in WML, separated by spaces instead of newlines. For values containing spaces, surround them with single quotes. The "text content" of a tag, if any, is usually given by a ''text'' key. You can't nest tags within another tag.

The following key/tags are accepted inside '''text''' ([https://github.com/wesnoth/wesnoth/blob/c09c58a8c8892d5f8392de48520a4f1b0ae1f35f/src/help/help_text_area.cpp#L126-L139 source]):
* {{anchor|ref|'''<ref>'''}}: creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.
** '''dst''': the ID of the topic to reference.
** '''text''': the text to display as a link to '''dst'''; i.e. when '''text''' is clicked on the page '''dst''' will be linked to.
** '''force''': shows the cross reference even though the referred topic is not shown.
* {{anchor|jump|'''<jump>'''}}: when this text is selected, the input position along the X axis is moved. Can be used for example to create columns of things. A jump is ignored if it would bring the input position to an invalid position.
** '''to''': the X coordinate of the text area to jump to. If it can't be done on the current row, the input position is moved down one line.
** '''amount''': the number of pixels to jump forward
* {{anchor|img|'''<img>'''}}: insert an image in the topic
** '''src''': the path to the image relative to the '''images/''' directory.
** '''align''': the position of the image with respect to the page. Values are '''here''', '''left''', '''middle''', and '''right'''.
** '''float''': whether the image should float(have text filled in around it) or not (be seen as included in a line).
* {{anchor|format|'''<format>'''}}: describes a group of text in a different format. Can be used to describe different colors and font sizes.
** '''bold''': whether the text should be displayed in bold('''bold''').
** '''italic''': whether the text should be displayed in italics(''italics'').
** '''color''': the color of the text. Only a few colors are currently supported: '''white'''(default), '''green''', '''red''', '''yellow''', and '''black'''.
** '''font_size''': the height of the text in pixels. Default 9(?)
** '''text''': the text to be displayed using this format.
* {{anchor|italic|'''<italic>'''}}: a shortcut to '''<format>''' which inputs only the '''text''' key. Uses the attribute '''italic=yes'''
* {{anchor|bold|'''<bold>'''}}: like <italic>, but uses '''bold=yes'''
* {{anchor|header|'''<header>'''}}: like <italic>, but uses both the attributes '''bold=yes''' and '''font_size=13'''(?)

Example:
<syntaxhighlight lang=wml>
[help]
[toplevel]
sections=introduction,gameplay
topics=about
[/toplevel]
[section]
id=gameplay
sections=combat
topics=income_and_upkeep,time_of_day,terrain,victory_and_defeat
[/section]
[topic]
id=terrain
title=Terrain
text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"
[/topic]
[topic]
id=victory_and_defeat
title= _ "Victory and Defeat"
text= _ "Pay careful attention to the <bold>text='Objectives'</bold> pop-up
box at the beginning of each scenario. Usually you will achieve
victory by killing all enemy leaders, and only be defeated by having
your leader killed. But scenarios may have other victory objectives
— getting your leader to a designated point, say, or rescuing someone,
or solving a puzzle, or holding out against a siege until a certain
number of turns have elapsed." + _"

When you win a scenario, the map grays over and the
<bold>text='End Turn'</bold> button changes to
<bold>text='End Scenario'</bold>. You can now do things like changing
your save options or (if you are in a multiplayer game) chatting with
other players before pressing that button to advance."

[/topic]
[/help]
</syntaxhighlight>

== See Also ==

* [[ReferenceWML]]
* [[Help_Markup|Help Markup]]

[[Category: WML Reference]]

WML Abilities

2025-04-06T14:07:47Z

Shiki: /* Soultaker */ grey out special on undrainable opponents

The more complex abilities and weapon specials often consist of two parts:
* The ability / weapon special, which is only a dummy to provide a description and to see whether a unit has this ability. It is something one gives to a unit. Mainline abilities / weapon specials only need this part.
* One or multiple [event]s, which make things happen. These can be included directly in the ability or weapon special tag {{DevFeature1.19|4}}. For earlier versions, these [event]s must be added to the game ''explicitly'', in addition to the unit with the ability or weapon special!

How to include [event]s?
* Add it inside the ability or weapon special tag. {{DevFeature1.19|4}}
* Add it directly to the scenario file.
* Add it directly to the [era].
* Add it inside a [unit_type] definition.
* Add it directly in your [campaign] tag.
* Add it inside a [resource], which is then loaded from your [campaign] tag or an individual scenario.
If you add it both via an [era] and and the scenario, they are added twice … i.e. the pickpocket ability would give the gold twice! To avoid that, give each event an '''id'''. This is even mandatory when adding it in a [unit_type].

Even better would be to use a [resource]. Resources have also an id, so there will never be duplicates:
* Instead of adding it to the scenario / era, you add the event code inside a [resource].
* The same way you read the scenario / era file, you also read the file containing the [resource] tag.
* In the scenario / era, use [[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
active_on=offense
[/dummy]
#enddef
</syntaxhighlight>

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
<syntaxhighlight lang='wml'>
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special_id=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_target_hex}
[/then]
[/if]
[/event]
</syntaxhighlight>

=== Charm ===

==== temporary ====

When a unit is hit by a ''charm'' attack, it instantly jumps to the attacker's side, and returns to its original side at the end of the turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

<syntaxhighlight lang='wml'>
#define CHARM FILTER WEAPON
[event]
name=attacker hits
# Works only as attacker.
# If you want to make a weapon special for this event, set:
# [dummy]active_on=offense, then the engine greys out the weapon special on defense.
first_time_only=no
id=charm_as_attacker

[filter]
{FILTER}
[/filter]

[filter_attack]
name={WEAPON}
# or special_id=charm, if you create a [dummy] weapon special
[/filter_attack]

[filter_second]
# If the leader is charmed, it might end the scenario,
# as the other side is now considered defeated without a leader.
# Better exclude leaders.
canrecruit=no
# If the unit would die from the damage,
# we should not interfere with the event.
formula="self.hitpoints > 0"
[/filter_second]

# Charm the unit
# Changing the side will also immediately stop the combat and grant both units XP
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[variables]
# to remember the original side
real_side=$second_unit.side
[/variables]
[status]
# optional, just to easier find the unit in the other event
charmed=yes
[/status]
side=$unit.side
moves=1
attacks_left=1
[/modify_unit]

[floating_text]
x,y=$x2,$y2
# po: short text, only displayed for a moment
text="<span color='#ffc0cb'>" + _ "charm" + "</span>"
[/floating_text]
[/event]

[event]
name=side turn end, scenario end
# Releasing the unit in the same turn has a few reasons:
# - a charmed unit cannot be charmed again
# - if the scenario ends, we can still correct the ownership
# - things like healing by allies work the usual way
first_time_only=no
id=charm_release

[store_unit]
[filter]
side=$side_number
status=charmed
[/filter]
variable=charmed_units
[/store_unit]

[foreach]
array=charmed_units
[do]
{VARIABLE this_item.side $this_item.variables.real_side}
{CLEAR_VARIABLE this_item.variables.real_side}
{CLEAR_VARIABLE this_item.status.charmed}
[unstore_unit]
variable=this_item
[/unstore_unit]
[/do]
[/foreach]

{CLEAR_VARIABLE charmed_units}
[/event]
#enddef
</syntaxhighlight>

==== permanent ====

This version of the weapon special is a gamble. You can obtain the other unit for good, but you also risk losing this unit. When you lose this unit, the opponent controls a unit with charm. You might regain it when he uses this weapon special.

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_CHARM
# dummy weapon special used to describe the effect to the user and filter on special's id.
[dummy]
id=weapon_charm
name= _ "charm"
description= _ "Turns a living level 1 or level 0 unit to your side. Beware, if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an enemy leader or a non-living creature."
apply_to=opponent
# The special will be displayed greyed out if these conditions do not match.
active_on=offense
[filter_opponent]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_opponent]
[/dummy]
#enddef

#define CHARMING_EVENTS
# Event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
id=charm_detect

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[modify_unit]
[filter]
id=$unit.id
[/filter]
[variables]
charm_has_worked=yes
[/variables]
[/modify_unit]
[/event]

# Event that shifts a unit to the other side,
# if the defending unit:
# - is lvl0 or lvl1
# - and is not a leader unit
# - and is a not a "non-living" creature
# Then:
# -> if the attacker missed all attacks, it goes to the defender’s side.
# -> if the attacker hit once at least, the defender goes to the attacker’s side.
[event]
name=attack_end
first_time_only=no
id=charm_convert

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[if]
[variable]
name=unit.variables.charm_has_worked
boolean_equals=no
[/variable]
[then]
{VARIABLE unit.side $second_unit.side}
[unstore_unit]
variable=unit
text= _ "Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
{VARIABLE second_unit.side $unit.side}
[unstore_unit]
variable=second_unit
text= _ "Charmed!"
{COLOR_HEAL}
[/unstore_unit]

# The variable needs to be unset as well.
{CLEAR_VARIABLE unit.variables.charm_has_worked}
[unstore_unit]
variable=unit
[/unstore_unit]
[/else]
[/if]
[/event]
#enddef
</syntaxhighlight>

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit having bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

<syntaxhighlight lang='wml'>
#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
moves=0
attacks_left=1
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special successfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_PICKPOCKET
# Canned definition of the pickpocket ability to be included in a
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
description= _ "Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
active_on=offense
[/dummy]
[/specials]
[/attack]

# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
boolean_equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer,pickpocketed}
[/event]
[+attack]
[+specials]
#enddef
</syntaxhighlight>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
[gold]
side=$side_number
amount='''X'''
[/gold]
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

[event]
'''name=attack_end'''
first_time_only=no

=== Soultaker ===

Any unit with this will gain an additional point of damage per strike every time it kills an enemy. Made for Melon’s Youkai faction (https://r.wesnoth.org/t20100). A variant which uses this as weapon special is used in ageless era (https://r.wesnoth.org/t25274).

One can add this as ability or as weapon special. As ability it will be used when the other unit is killed by any attack of this unit. Using it as weapon special is similar to the Necromancer’s plague staff: It will only take effect when the attack with the special is used to land the killing blow.

Place the following in any .cfg file loaded by the campaign or era:

<syntaxhighlight lang='wml'>
#define SOULTAKER_DUMMY
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "This unit gains an additional point added to its melee damage whenever it kills a living unit."
[filter_opponent]
[not]
status=undrainable
[/not]
[/filter_opponent]
[/dummy]
#enddef

#define SOULTAKER_EVENT
[event]
name=die
first_time_only=no
id=soultaker

[filter]
[not]
status=undrainable
[/not]
[/filter]

# Use this check if you want to use Soultaker as ability.
[filter_second]
ability=soultaker
[/filter_second]

# To use Soultaker as weapon special, use this check INSTEAD of the above one.
# [filter_second_attack]
# special_id=soultaker
# [/filter_second_attack]

[floating_text]
x,y=$x2,$y2
text="<span color='#00ff00'>" + _ "+1 damage" + "</span>"
[/floating_text]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
increase_damage=1
range=melee
# This will increase all melee attacks by 1. To only increase the attack used in this fight, use
# name=$second_weapon.name
[/effect]
[/object]
[/event]
#enddef
</syntaxhighlight>

And the following in the unit's [abilities] tag. If you changed the code to use the weapon special variant, add instead to the unit’s [attack] an [specials] tag, into which you place:

{SOULTAKER_DUMMY}

Add to the [campaign] or [era] tag:

{SOULTAKER_EVENT}

== Works ==

Unit with ability ''works'' will produce 1 gold per turn. This mechanism is used in the mainline multiplayer map »A New Land«.

Put this macro into you code before the last piece of code.
<syntaxhighlight lang='wml'>
#define ABILITY_WORKS
[works]
id=peasant_works
name="works"
description= _ "This unit produces 1 gold per turn."
[/works]
#enddef
</syntaxhighlight>

Put this event into your code.
<syntaxhighlight lang='wml'>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
ability=peasant_works
side=$side_number
[/filter]
variable=workers
[/store_unit]

[foreach]
array=workers
[do]
[gold]
side=$this_item.side
amount=1
[/gold]
[floating_text]
x,y=$this_item.x,$this_item.y
text="<span color='#ffff00'>" + _ "+1 gold" + "</span>"
[/floating_text]
[/do]
[/foreach]

{CLEAR_VARIABLE workers}
[/event]
</syntaxhighlight>

And give the unit the ability like this:
<syntaxhighlight lang='wml'>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</syntaxhighlight>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name= _ "Mind Flay"
description= _ "When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
active_on=offense
[/mindflay]
#enddef
</syntaxhighlight>

Include these events into your scenario:
<syntaxhighlight lang='wml'>
[event]
name=attack
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP second_unit.experience sub $hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]
</syntaxhighlight>

== Initiative ==

Initiative is an aura ability. Much like leadership, it affects adjacent allies but not the unit itself.

The ability is used in HttT by Li’sar, you can copy the code from [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Heir_To_The_Throne/utils/abilities.cfg data/campaigns/Heir_To_The_Throne/utils/abilities.cfg]

== Blitz ==

UtBS and TroW have with ''distract'' an ability, which lets adjacent units ignore the ZoC. It works similar to leadership and initiative, the bonus is valid ''while'' the unit is adjacent.

This ability does the same, but it works similar to healing: The bonus is applied at the beginning of the turn and still valid when not anymore being adjacent.

But it also differs from the way healing works for allied units:
* With healing, it is useful if you move your injured unit to an ally, so that it is adjacent at the healing time.
* With this ability, the unit who wants the bonus must be adjacent at the start of <i>his own</i> turn.

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ
[dummy]
id=blitz
name= _ "blitz"
description= _ "Allies that start their turn adjacent to this unit are granted skirmisher for that turn."
special_note= _ "Instead of healing other units, this unit grants temporarily skirmisher for allied units at the beginning of their turn."
active_on=offense
affect_self=no
affect_allies=yes
[affect_adjacent][/affect_adjacent]
[/dummy]
#enddef
</syntaxhighlight>

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ_EVENT
[event]
name=side turn
first_time_only=no

[modify_unit]
# The units adjacent to a unit with the blitz ability …
[filter]
side=$side_number
[filter_adjacent]
is_enemy=no
ability=blitz
[/filter_adjacent]
[/filter]

# … receive temporarily this ability.
[object]
duration=turn end
[effect]
apply_to=new_ability
[abilities]
{ABILITY_SKIRMISHER}
[/abilities]
[/effect]
[/object]
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

== Immune to drain or plague or poison ==

To make a unit immune to plague, poison or/and draining of life force, set the right [status] for this unit: One or multiple of '''unpoisonable''', '''undrainable''', '''unplagueable'''.

There are many ways to change a status, it can be set directly with [modify_unit], at recruitment via a [trait], or by giving the unit an [object]. In mainline, a [trait] is used to make undead units immune. Traits also have a name and description, which can be used to make it visible to the player that this unit is immune.

<syntaxhighlight lang='wml'>
#define TRAIT_UNDRAINABLE
# We make vampires undrainable with a trait.
# Traits show up in the help browser, thus they should have proper descriptions.
[trait]
id=undrainable
availability=musthave
male_name= _ "vampire"
female_name= _ "female^vampire"
description= _ "This unit’s life force cannot be drained."
help_text= _ "Vampires are like Undead immune to drain and plague, but still susceptible to poison. While this trait is usually seen among vampire units, other mythical beings have also been seen with it. Even some Mages managed to acquire it."
# vampire is not a good name for a trait, as you can give the trait to anybody
[effect]
apply_to=status
add=undrainable
[/effect]
[effect]
apply_to=status
add=unplagueable
[/effect]
[/trait]
#enddef
</syntaxhighlight>

When you define a new [unit'''_type'''], add to it:
{TRAIT_UNDRAINABLE}
num_traits=3 # if you still want it to get 2 other traits

In other cases, if you want to make unit immune, i.e. one from mainline, give it the trait another way:
<syntaxhighlight lang='wml'>
[event]
name=prerecruit
first_time_only=no
[filter]
type_adv_tree=Mage
[or]
race=elf
side=2
[/or]
[/filter]

[modify_unit]
[filter]
id=$unit.id
[/filter]
{TRAIT_UNDRAINABLE}

# Or without trait / object:
# [status]
# undrainable=yes
# [/status]
[/modify_unit]
[/event]
</syntaxhighlight>

== Whirlwind Attack ==

This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it:

<syntaxhighlight lang='wml'>
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
description= _ "When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
active_on=offense
[/attacks]
</syntaxhighlight>

This is the event:
<syntaxhighlight lang='wml'>
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=whirlwind
[/filter_attack]
{VARIABLE has_drain no} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}
[/then]
[/if]
[if]
[variable]
name=has_drain
boolean_equals=yes
[/variable]
[then]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not]
status=undrainable,petrified
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
[foreach]
array=units
[do]
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($this_item.resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($this_item.resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($this_item.resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($this_item.resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($this_item.resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($this_item.resistance.impact*$weapon.damage)"}
[/case]
[/switch]
[/do]
[/foreach]
#Float the healed amount over the unit, like if it had drained
[floating_text] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1 #Operating with huge numbers because rounding is a problem
text="<span color='#00ff00'>" + "$($healed_amount/200)" + "</span>"
[/floating_text]
[heal_unit]
[filter]
x,y=$x1,$y1
[/filter]
amount=$($healed_amount/200)
restore_statuses=no
animate=no
[/heal_unit]
{CLEAR_VARIABLE units,healed_amount}
[/then]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not]
x,y=$x2,$y2
[/not]
[not]
status=petrified
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow,has_poison,has_drain}
[/event]
</syntaxhighlight>

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

WML Abilities

2025-04-06T14:06:51Z

Shiki: /* Soultaker */ indent

The more complex abilities and weapon specials often consist of two parts:
* The ability / weapon special, which is only a dummy to provide a description and to see whether a unit has this ability. It is something one gives to a unit. Mainline abilities / weapon specials only need this part.
* One or multiple [event]s, which make things happen. These can be included directly in the ability or weapon special tag {{DevFeature1.19|4}}. For earlier versions, these [event]s must be added to the game ''explicitly'', in addition to the unit with the ability or weapon special!

How to include [event]s?
* Add it inside the ability or weapon special tag. {{DevFeature1.19|4}}
* Add it directly to the scenario file.
* Add it directly to the [era].
* Add it inside a [unit_type] definition.
* Add it directly in your [campaign] tag.
* Add it inside a [resource], which is then loaded from your [campaign] tag or an individual scenario.
If you add it both via an [era] and and the scenario, they are added twice … i.e. the pickpocket ability would give the gold twice! To avoid that, give each event an '''id'''. This is even mandatory when adding it in a [unit_type].

Even better would be to use a [resource]. Resources have also an id, so there will never be duplicates:
* Instead of adding it to the scenario / era, you add the event code inside a [resource].
* The same way you read the scenario / era file, you also read the file containing the [resource] tag.
* In the scenario / era, use [[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
active_on=offense
[/dummy]
#enddef
</syntaxhighlight>

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
<syntaxhighlight lang='wml'>
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special_id=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_target_hex}
[/then]
[/if]
[/event]
</syntaxhighlight>

=== Charm ===

==== temporary ====

When a unit is hit by a ''charm'' attack, it instantly jumps to the attacker's side, and returns to its original side at the end of the turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

<syntaxhighlight lang='wml'>
#define CHARM FILTER WEAPON
[event]
name=attacker hits
# Works only as attacker.
# If you want to make a weapon special for this event, set:
# [dummy]active_on=offense, then the engine greys out the weapon special on defense.
first_time_only=no
id=charm_as_attacker

[filter]
{FILTER}
[/filter]

[filter_attack]
name={WEAPON}
# or special_id=charm, if you create a [dummy] weapon special
[/filter_attack]

[filter_second]
# If the leader is charmed, it might end the scenario,
# as the other side is now considered defeated without a leader.
# Better exclude leaders.
canrecruit=no
# If the unit would die from the damage,
# we should not interfere with the event.
formula="self.hitpoints > 0"
[/filter_second]

# Charm the unit
# Changing the side will also immediately stop the combat and grant both units XP
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[variables]
# to remember the original side
real_side=$second_unit.side
[/variables]
[status]
# optional, just to easier find the unit in the other event
charmed=yes
[/status]
side=$unit.side
moves=1
attacks_left=1
[/modify_unit]

[floating_text]
x,y=$x2,$y2
# po: short text, only displayed for a moment
text="<span color='#ffc0cb'>" + _ "charm" + "</span>"
[/floating_text]
[/event]

[event]
name=side turn end, scenario end
# Releasing the unit in the same turn has a few reasons:
# - a charmed unit cannot be charmed again
# - if the scenario ends, we can still correct the ownership
# - things like healing by allies work the usual way
first_time_only=no
id=charm_release

[store_unit]
[filter]
side=$side_number
status=charmed
[/filter]
variable=charmed_units
[/store_unit]

[foreach]
array=charmed_units
[do]
{VARIABLE this_item.side $this_item.variables.real_side}
{CLEAR_VARIABLE this_item.variables.real_side}
{CLEAR_VARIABLE this_item.status.charmed}
[unstore_unit]
variable=this_item
[/unstore_unit]
[/do]
[/foreach]

{CLEAR_VARIABLE charmed_units}
[/event]
#enddef
</syntaxhighlight>

==== permanent ====

This version of the weapon special is a gamble. You can obtain the other unit for good, but you also risk losing this unit. When you lose this unit, the opponent controls a unit with charm. You might regain it when he uses this weapon special.

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_CHARM
# dummy weapon special used to describe the effect to the user and filter on special's id.
[dummy]
id=weapon_charm
name= _ "charm"
description= _ "Turns a living level 1 or level 0 unit to your side. Beware, if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an enemy leader or a non-living creature."
apply_to=opponent
# The special will be displayed greyed out if these conditions do not match.
active_on=offense
[filter_opponent]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_opponent]
[/dummy]
#enddef

#define CHARMING_EVENTS
# Event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
id=charm_detect

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[modify_unit]
[filter]
id=$unit.id
[/filter]
[variables]
charm_has_worked=yes
[/variables]
[/modify_unit]
[/event]

# Event that shifts a unit to the other side,
# if the defending unit:
# - is lvl0 or lvl1
# - and is not a leader unit
# - and is a not a "non-living" creature
# Then:
# -> if the attacker missed all attacks, it goes to the defender’s side.
# -> if the attacker hit once at least, the defender goes to the attacker’s side.
[event]
name=attack_end
first_time_only=no
id=charm_convert

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[if]
[variable]
name=unit.variables.charm_has_worked
boolean_equals=no
[/variable]
[then]
{VARIABLE unit.side $second_unit.side}
[unstore_unit]
variable=unit
text= _ "Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
{VARIABLE second_unit.side $unit.side}
[unstore_unit]
variable=second_unit
text= _ "Charmed!"
{COLOR_HEAL}
[/unstore_unit]

# The variable needs to be unset as well.
{CLEAR_VARIABLE unit.variables.charm_has_worked}
[unstore_unit]
variable=unit
[/unstore_unit]
[/else]
[/if]
[/event]
#enddef
</syntaxhighlight>

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit having bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

<syntaxhighlight lang='wml'>
#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
moves=0
attacks_left=1
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special successfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_PICKPOCKET
# Canned definition of the pickpocket ability to be included in a
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
description= _ "Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
active_on=offense
[/dummy]
[/specials]
[/attack]

# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
boolean_equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer,pickpocketed}
[/event]
[+attack]
[+specials]
#enddef
</syntaxhighlight>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
[gold]
side=$side_number
amount='''X'''
[/gold]
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

[event]
'''name=attack_end'''
first_time_only=no

=== Soultaker ===

Any unit with this will gain an additional point of damage per strike every time it kills an enemy. Made for Melon’s Youkai faction (https://r.wesnoth.org/t20100). A variant which uses this as weapon special is used in ageless era (https://r.wesnoth.org/t25274).

One can add this as ability or as weapon special. As ability it will be used when the other unit is killed by any attack of this unit. Using it as weapon special is similar to the Necromancer’s plague staff: It will only take effect when the attack with the special is used to land the killing blow.

Place the following in any .cfg file loaded by the campaign or era:

<syntaxhighlight lang='wml'>
#define SOULTAKER_DUMMY
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "This unit gains an additional point added to its melee damage whenever it kills a living unit."
[/dummy]
#enddef

#define SOULTAKER_EVENT
[event]
name=die
first_time_only=no
id=soultaker

[filter]
[not]
status=undrainable
[/not]
[/filter]

# Use this check if you want to use Soultaker as ability.
[filter_second]
ability=soultaker
[/filter_second]

# To use Soultaker as weapon special, use this check INSTEAD of the above one.
# [filter_second_attack]
# special_id=soultaker
# [/filter_second_attack]

[floating_text]
x,y=$x2,$y2
text="<span color='#00ff00'>" + _ "+1 damage" + "</span>"
[/floating_text]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
increase_damage=1
range=melee
# This will increase all melee attacks by 1. To only increase the attack used in this fight, use
# name=$second_weapon.name
[/effect]
[/object]
[/event]
#enddef
</syntaxhighlight>

And the following in the unit's [abilities] tag. If you changed the code to use the weapon special variant, add instead to the unit’s [attack] an [specials] tag, into which you place:

{SOULTAKER_DUMMY}

Add to the [campaign] or [era] tag:

{SOULTAKER_EVENT}

== Works ==

Unit with ability ''works'' will produce 1 gold per turn. This mechanism is used in the mainline multiplayer map »A New Land«.

Put this macro into you code before the last piece of code.
<syntaxhighlight lang='wml'>
#define ABILITY_WORKS
[works]
id=peasant_works
name="works"
description= _ "This unit produces 1 gold per turn."
[/works]
#enddef
</syntaxhighlight>

Put this event into your code.
<syntaxhighlight lang='wml'>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
ability=peasant_works
side=$side_number
[/filter]
variable=workers
[/store_unit]

[foreach]
array=workers
[do]
[gold]
side=$this_item.side
amount=1
[/gold]
[floating_text]
x,y=$this_item.x,$this_item.y
text="<span color='#ffff00'>" + _ "+1 gold" + "</span>"
[/floating_text]
[/do]
[/foreach]

{CLEAR_VARIABLE workers}
[/event]
</syntaxhighlight>

And give the unit the ability like this:
<syntaxhighlight lang='wml'>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</syntaxhighlight>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name= _ "Mind Flay"
description= _ "When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
active_on=offense
[/mindflay]
#enddef
</syntaxhighlight>

Include these events into your scenario:
<syntaxhighlight lang='wml'>
[event]
name=attack
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP second_unit.experience sub $hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]
</syntaxhighlight>

== Initiative ==

Initiative is an aura ability. Much like leadership, it affects adjacent allies but not the unit itself.

The ability is used in HttT by Li’sar, you can copy the code from [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Heir_To_The_Throne/utils/abilities.cfg data/campaigns/Heir_To_The_Throne/utils/abilities.cfg]

== Blitz ==

UtBS and TroW have with ''distract'' an ability, which lets adjacent units ignore the ZoC. It works similar to leadership and initiative, the bonus is valid ''while'' the unit is adjacent.

This ability does the same, but it works similar to healing: The bonus is applied at the beginning of the turn and still valid when not anymore being adjacent.

But it also differs from the way healing works for allied units:
* With healing, it is useful if you move your injured unit to an ally, so that it is adjacent at the healing time.
* With this ability, the unit who wants the bonus must be adjacent at the start of <i>his own</i> turn.

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ
[dummy]
id=blitz
name= _ "blitz"
description= _ "Allies that start their turn adjacent to this unit are granted skirmisher for that turn."
special_note= _ "Instead of healing other units, this unit grants temporarily skirmisher for allied units at the beginning of their turn."
active_on=offense
affect_self=no
affect_allies=yes
[affect_adjacent][/affect_adjacent]
[/dummy]
#enddef
</syntaxhighlight>

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ_EVENT
[event]
name=side turn
first_time_only=no

[modify_unit]
# The units adjacent to a unit with the blitz ability …
[filter]
side=$side_number
[filter_adjacent]
is_enemy=no
ability=blitz
[/filter_adjacent]
[/filter]

# … receive temporarily this ability.
[object]
duration=turn end
[effect]
apply_to=new_ability
[abilities]
{ABILITY_SKIRMISHER}
[/abilities]
[/effect]
[/object]
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

== Immune to drain or plague or poison ==

To make a unit immune to plague, poison or/and draining of life force, set the right [status] for this unit: One or multiple of '''unpoisonable''', '''undrainable''', '''unplagueable'''.

There are many ways to change a status, it can be set directly with [modify_unit], at recruitment via a [trait], or by giving the unit an [object]. In mainline, a [trait] is used to make undead units immune. Traits also have a name and description, which can be used to make it visible to the player that this unit is immune.

<syntaxhighlight lang='wml'>
#define TRAIT_UNDRAINABLE
# We make vampires undrainable with a trait.
# Traits show up in the help browser, thus they should have proper descriptions.
[trait]
id=undrainable
availability=musthave
male_name= _ "vampire"
female_name= _ "female^vampire"
description= _ "This unit’s life force cannot be drained."
help_text= _ "Vampires are like Undead immune to drain and plague, but still susceptible to poison. While this trait is usually seen among vampire units, other mythical beings have also been seen with it. Even some Mages managed to acquire it."
# vampire is not a good name for a trait, as you can give the trait to anybody
[effect]
apply_to=status
add=undrainable
[/effect]
[effect]
apply_to=status
add=unplagueable
[/effect]
[/trait]
#enddef
</syntaxhighlight>

When you define a new [unit'''_type'''], add to it:
{TRAIT_UNDRAINABLE}
num_traits=3 # if you still want it to get 2 other traits

In other cases, if you want to make unit immune, i.e. one from mainline, give it the trait another way:
<syntaxhighlight lang='wml'>
[event]
name=prerecruit
first_time_only=no
[filter]
type_adv_tree=Mage
[or]
race=elf
side=2
[/or]
[/filter]

[modify_unit]
[filter]
id=$unit.id
[/filter]
{TRAIT_UNDRAINABLE}

# Or without trait / object:
# [status]
# undrainable=yes
# [/status]
[/modify_unit]
[/event]
</syntaxhighlight>

== Whirlwind Attack ==

This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it:

<syntaxhighlight lang='wml'>
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
description= _ "When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
active_on=offense
[/attacks]
</syntaxhighlight>

This is the event:
<syntaxhighlight lang='wml'>
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=whirlwind
[/filter_attack]
{VARIABLE has_drain no} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}
[/then]
[/if]
[if]
[variable]
name=has_drain
boolean_equals=yes
[/variable]
[then]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not]
status=undrainable,petrified
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
[foreach]
array=units
[do]
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($this_item.resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($this_item.resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($this_item.resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($this_item.resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($this_item.resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($this_item.resistance.impact*$weapon.damage)"}
[/case]
[/switch]
[/do]
[/foreach]
#Float the healed amount over the unit, like if it had drained
[floating_text] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1 #Operating with huge numbers because rounding is a problem
text="<span color='#00ff00'>" + "$($healed_amount/200)" + "</span>"
[/floating_text]
[heal_unit]
[filter]
x,y=$x1,$y1
[/filter]
amount=$($healed_amount/200)
restore_statuses=no
animate=no
[/heal_unit]
{CLEAR_VARIABLE units,healed_amount}
[/then]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not]
x,y=$x2,$y2
[/not]
[not]
status=petrified
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow,has_poison,has_drain}
[/event]
</syntaxhighlight>

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

WML Abilities

2025-04-06T13:55:18Z

Shiki: Charm

The more complex abilities and weapon specials often consist of two parts:
* The ability / weapon special, which is only a dummy to provide a description and to see whether a unit has this ability. It is something one gives to a unit. Mainline abilities / weapon specials only need this part.
* One or multiple [event]s, which make things happen. These can be included directly in the ability or weapon special tag {{DevFeature1.19|4}}. For earlier versions, these [event]s must be added to the game ''explicitly'', in addition to the unit with the ability or weapon special!

How to include [event]s?
* Add it inside the ability or weapon special tag. {{DevFeature1.19|4}}
* Add it directly to the scenario file.
* Add it directly to the [era].
* Add it inside a [unit_type] definition.
* Add it directly in your [campaign] tag.
* Add it inside a [resource], which is then loaded from your [campaign] tag or an individual scenario.
If you add it both via an [era] and and the scenario, they are added twice … i.e. the pickpocket ability would give the gold twice! To avoid that, give each event an '''id'''. This is even mandatory when adding it in a [unit_type].

Even better would be to use a [resource]. Resources have also an id, so there will never be duplicates:
* Instead of adding it to the scenario / era, you add the event code inside a [resource].
* The same way you read the scenario / era file, you also read the file containing the [resource] tag.
* In the scenario / era, use [[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
active_on=offense
[/dummy]
#enddef
</syntaxhighlight>

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
<syntaxhighlight lang='wml'>
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special_id=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_target_hex}
[/then]
[/if]
[/event]
</syntaxhighlight>

=== Charm ===

==== temporary ====

When a unit is hit by a ''charm'' attack, it instantly jumps to the attacker's side, and returns to its original side at the end of the turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

<syntaxhighlight lang='wml'>
#define CHARM FILTER WEAPON
[event]
name=attacker hits
# Works only as attacker.
# If you want to make a weapon special for this event, set:
# [dummy]active_on=offense, then the engine greys out the weapon special on defense.
first_time_only=no
id=charm_as_attacker

[filter]
{FILTER}
[/filter]

[filter_attack]
name={WEAPON}
# or special_id=charm, if you create a [dummy] weapon special
[/filter_attack]

[filter_second]
# If the leader is charmed, it might end the scenario,
# as the other side is now considered defeated without a leader.
# Better exclude leaders.
canrecruit=no
# If the unit would die from the damage,
# we should not interfere with the event.
formula="self.hitpoints > 0"
[/filter_second]

# Charm the unit
# Changing the side will also immediately stop the combat and grant both units XP
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[variables]
# to remember the original side
real_side=$second_unit.side
[/variables]
[status]
# optional, just to easier find the unit in the other event
charmed=yes
[/status]
side=$unit.side
moves=1
attacks_left=1
[/modify_unit]

[floating_text]
x,y=$x2,$y2
# po: short text, only displayed for a moment
text="<span color='#ffc0cb'>" + _ "charm" + "</span>"
[/floating_text]
[/event]

[event]
name=side turn end, scenario end
# Releasing the unit in the same turn has a few reasons:
# - a charmed unit cannot be charmed again
# - if the scenario ends, we can still correct the ownership
# - things like healing by allies work the usual way
first_time_only=no
id=charm_release

[store_unit]
[filter]
side=$side_number
status=charmed
[/filter]
variable=charmed_units
[/store_unit]

[foreach]
array=charmed_units
[do]
{VARIABLE this_item.side $this_item.variables.real_side}
{CLEAR_VARIABLE this_item.variables.real_side}
{CLEAR_VARIABLE this_item.status.charmed}
[unstore_unit]
variable=this_item
[/unstore_unit]
[/do]
[/foreach]

{CLEAR_VARIABLE charmed_units}
[/event]
#enddef
</syntaxhighlight>

==== permanent ====

This version of the weapon special is a gamble. You can obtain the other unit for good, but you also risk losing this unit. When you lose this unit, the opponent controls a unit with charm. You might regain it when he uses this weapon special.

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_CHARM
# dummy weapon special used to describe the effect to the user and filter on special's id.
[dummy]
id=weapon_charm
name= _ "charm"
description= _ "Turns a living level 1 or level 0 unit to your side. Beware, if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an enemy leader or a non-living creature."
apply_to=opponent
# The special will be displayed greyed out if these conditions do not match.
active_on=offense
[filter_opponent]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_opponent]
[/dummy]
#enddef

#define CHARMING_EVENTS
# Event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
id=charm_detect

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[modify_unit]
[filter]
id=$unit.id
[/filter]
[variables]
charm_has_worked=yes
[/variables]
[/modify_unit]
[/event]

# Event that shifts a unit to the other side,
# if the defending unit:
# - is lvl0 or lvl1
# - and is not a leader unit
# - and is a not a "non-living" creature
# Then:
# -> if the attacker missed all attacks, it goes to the defender’s side.
# -> if the attacker hit once at least, the defender goes to the attacker’s side.
[event]
name=attack_end
first_time_only=no
id=charm_convert

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[if]
[variable]
name=unit.variables.charm_has_worked
boolean_equals=no
[/variable]
[then]
{VARIABLE unit.side $second_unit.side}
[unstore_unit]
variable=unit
text= _ "Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
{VARIABLE second_unit.side $unit.side}
[unstore_unit]
variable=second_unit
text= _ "Charmed!"
{COLOR_HEAL}
[/unstore_unit]

# The variable needs to be unset as well.
{CLEAR_VARIABLE unit.variables.charm_has_worked}
[unstore_unit]
variable=unit
[/unstore_unit]
[/else]
[/if]
[/event]
#enddef
</syntaxhighlight>

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit having bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

<syntaxhighlight lang='wml'>
#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
moves=0
attacks_left=1
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special successfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_PICKPOCKET
# Canned definition of the pickpocket ability to be included in a
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
description= _ "Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
active_on=offense
[/dummy]
[/specials]
[/attack]

# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
boolean_equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer,pickpocketed}
[/event]
[+attack]
[+specials]
#enddef
</syntaxhighlight>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
[gold]
side=$side_number
amount='''X'''
[/gold]
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

[event]
'''name=attack_end'''
first_time_only=no

=== Soultaker ===

Any unit with this will gain an additional point of damage per strike every time it kills an enemy. Made for Melon’s Youkai faction (https://r.wesnoth.org/t20100). A variant which uses this as weapon special is used in ageless era (https://r.wesnoth.org/t25274).

One can add this as ability or as weapon special. As ability it will be used when the other unit is killed by any attack of this unit. Using it as weapon special is similar to the Necromancer’s plague staff: It will only take effect when the attack with the special is used to land the killing blow.

Place the following in any .cfg file loaded by the campaign or era:

<syntaxhighlight lang='wml'>
#define SOULTAKER_DUMMY
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "This unit gains an additional point added to its melee damage whenever it kills a living unit."
[/dummy]
#enddef

#define SOULTAKER_EVENT
[event]
name=die
first_time_only=no
id=soultaker

[filter]
[not]
status=undrainable
[/not]
[/filter]

# Use this check if you want to use Soultaker as ability.
[filter_second]
ability=soultaker
[/filter_second]

# To use Soultaker as weapon special, use this check INSTEAD of the above one.
# [filter_second_attack]
# special_id=soultaker
# [/filter_second_attack]

[floating_text]
x,y=$x2,$y2
text="<span color='#00ff00'>" + _ "+1 damage" + "</span>"
[/floating_text]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
increase_damage=1
range=melee
# This will increase all melee attacks by 1. To only increase the attack used in this fight, use
# name=$second_weapon.name
[/effect]
[/object]
[/event]
#enddef
</syntaxhighlight>

And the following in the unit's [abilities] tag. If you changed the code to use the weapon special variant, add instead to the unit’s [attack] an [specials] tag, into which you place:

{SOULTAKER_DUMMY}

Add to the [campaign] or [era] tag:

{SOULTAKER_EVENT}

== Works ==

Unit with ability ''works'' will produce 1 gold per turn. This mechanism is used in the mainline multiplayer map »A New Land«.

Put this macro into you code before the last piece of code.
<syntaxhighlight lang='wml'>
#define ABILITY_WORKS
[works]
id=peasant_works
name="works"
description= _ "This unit produces 1 gold per turn."
[/works]
#enddef
</syntaxhighlight>

Put this event into your code.
<syntaxhighlight lang='wml'>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
ability=peasant_works
side=$side_number
[/filter]
variable=workers
[/store_unit]

[foreach]
array=workers
[do]
[gold]
side=$this_item.side
amount=1
[/gold]
[floating_text]
x,y=$this_item.x,$this_item.y
text="<span color='#ffff00'>" + _ "+1 gold" + "</span>"
[/floating_text]
[/do]
[/foreach]

{CLEAR_VARIABLE workers}
[/event]
</syntaxhighlight>

And give the unit the ability like this:
<syntaxhighlight lang='wml'>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</syntaxhighlight>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name= _ "Mind Flay"
description= _ "When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
active_on=offense
[/mindflay]
#enddef
</syntaxhighlight>

Include these events into your scenario:
<syntaxhighlight lang='wml'>
[event]
name=attack
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP second_unit.experience sub $hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]
</syntaxhighlight>

== Initiative ==

Initiative is an aura ability. Much like leadership, it affects adjacent allies but not the unit itself.

The ability is used in HttT by Li’sar, you can copy the code from [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Heir_To_The_Throne/utils/abilities.cfg data/campaigns/Heir_To_The_Throne/utils/abilities.cfg]

== Blitz ==

UtBS and TroW have with ''distract'' an ability, which lets adjacent units ignore the ZoC. It works similar to leadership and initiative, the bonus is valid ''while'' the unit is adjacent.

This ability does the same, but it works similar to healing: The bonus is applied at the beginning of the turn and still valid when not anymore being adjacent.

But it also differs from the way healing works for allied units:
* With healing, it is useful if you move your injured unit to an ally, so that it is adjacent at the healing time.
* With this ability, the unit who wants the bonus must be adjacent at the start of <i>his own</i> turn.

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ
[dummy]
id=blitz
name= _ "blitz"
description= _ "Allies that start their turn adjacent to this unit are granted skirmisher for that turn."
special_note= _ "Instead of healing other units, this unit grants temporarily skirmisher for allied units at the beginning of their turn."
active_on=offense
affect_self=no
affect_allies=yes
[affect_adjacent][/affect_adjacent]
[/dummy]
#enddef
</syntaxhighlight>

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ_EVENT
[event]
name=side turn
first_time_only=no

[modify_unit]
# The units adjacent to a unit with the blitz ability …
[filter]
side=$side_number
[filter_adjacent]
is_enemy=no
ability=blitz
[/filter_adjacent]
[/filter]

# … receive temporarily this ability.
[object]
duration=turn end
[effect]
apply_to=new_ability
[abilities]
{ABILITY_SKIRMISHER}
[/abilities]
[/effect]
[/object]
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

== Immune to drain or plague or poison ==

To make a unit immune to plague, poison or/and draining of life force, set the right [status] for this unit: One or multiple of '''unpoisonable''', '''undrainable''', '''unplagueable'''.

There are many ways to change a status, it can be set directly with [modify_unit], at recruitment via a [trait], or by giving the unit an [object]. In mainline, a [trait] is used to make undead units immune. Traits also have a name and description, which can be used to make it visible to the player that this unit is immune.

<syntaxhighlight lang='wml'>
#define TRAIT_UNDRAINABLE
# We make vampires undrainable with a trait.
# Traits show up in the help browser, thus they should have proper descriptions.
[trait]
id=undrainable
availability=musthave
male_name= _ "vampire"
female_name= _ "female^vampire"
description= _ "This unit’s life force cannot be drained."
help_text= _ "Vampires are like Undead immune to drain and plague, but still susceptible to poison. While this trait is usually seen among vampire units, other mythical beings have also been seen with it. Even some Mages managed to acquire it."
# vampire is not a good name for a trait, as you can give the trait to anybody
[effect]
apply_to=status
add=undrainable
[/effect]
[effect]
apply_to=status
add=unplagueable
[/effect]
[/trait]
#enddef
</syntaxhighlight>

When you define a new [unit'''_type'''], add to it:
{TRAIT_UNDRAINABLE}
num_traits=3 # if you still want it to get 2 other traits

In other cases, if you want to make unit immune, i.e. one from mainline, give it the trait another way:
<syntaxhighlight lang='wml'>
[event]
name=prerecruit
first_time_only=no
[filter]
type_adv_tree=Mage
[or]
race=elf
side=2
[/or]
[/filter]

[modify_unit]
[filter]
id=$unit.id
[/filter]
{TRAIT_UNDRAINABLE}

# Or without trait / object:
# [status]
# undrainable=yes
# [/status]
[/modify_unit]
[/event]
</syntaxhighlight>

== Whirlwind Attack ==

This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it:

<syntaxhighlight lang='wml'>
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
description= _ "When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
active_on=offense
[/attacks]
</syntaxhighlight>

This is the event:
<syntaxhighlight lang='wml'>
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=whirlwind
[/filter_attack]
{VARIABLE has_drain no} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}
[/then]
[/if]
[if]
[variable]
name=has_drain
boolean_equals=yes
[/variable]
[then]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not]
status=undrainable,petrified
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
[foreach]
array=units
[do]
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($this_item.resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($this_item.resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($this_item.resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($this_item.resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($this_item.resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($this_item.resistance.impact*$weapon.damage)"}
[/case]
[/switch]
[/do]
[/foreach]
#Float the healed amount over the unit, like if it had drained
[floating_text] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1 #Operating with huge numbers because rounding is a problem
text="<span color='#00ff00'>" + "$($healed_amount/200)" + "</span>"
[/floating_text]
[heal_unit]
[filter]
x,y=$x1,$y1
[/filter]
amount=$($healed_amount/200)
restore_statuses=no
animate=no
[/heal_unit]
{CLEAR_VARIABLE units,healed_amount}
[/then]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not]
x,y=$x2,$y2
[/not]
[not]
status=petrified
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow,has_poison,has_drain}
[/event]
</syntaxhighlight>

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

SideWML

2025-03-24T13:53:46Z

Shiki: document [variables]

{{WML Tags}}

The term "side" refers to a single player in the Wesnoth turn order, which can be controlled by either a human or an AI. Every [[ScenarioWML|scenario]] must have at least one side. There is no hard limit on the number of sides a single scenario can have.

Usually the number of sides in a scenario is fixed. However, the Lua function [[LuaAPI/wesnoth/sides#wesnoth.sides.create|wesnoth.sides.create]] can be used to dynamically add new sides if required.

Sides in a scenario are described by the '''[side]''' tag, which recognizes the following keys and tags.

== Common Keys ==

These keys are always permitted in a '''[side]''' tag.

* '''side''': a number. The leader of this side is placed on the tile represented by this number (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides. {{DevFeature1.13|2}} The server doesn't limit the number of sides anymore.

* {{anchor|controller|'''controller'''}} (required): how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move. Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and ''side turn'' events.
** '''a number''': gives this side's control to a side with '''side''' matching the number (multiplayer only). {{DevFeature1.13|2}} using a number is deprecated, use previous_save_id= instead.
** Note: in multiplayer, when reading the side's data with ''[store_side]'', the value may differ between clients and using it for conditional actions may cause OOS. Discussion in https://r.wesnoth.org/p643343

* '''type''': if present, the keys describing a unit (including '''type''') which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using ''canrecruit=yes'') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are ''id'', ''name'' and ''unrenamable=yes'', see [[SingleUnitWML]]. The unit will automatically be set to be able to recruit.

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units. Units in the side recruit list can always be recruited by a leader on this side, in addition to any units in the individual leader's '''extra_recruit''' list. {{DevFeature1.13|?}} in multiplayer, unless you specify ''faction=Custom'', this will be overwritten by the recruit list from the faction.

* '''gold''': the starting gold for this side. Default: 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': the base income for this side. Default: 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).

* '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''fog_data''': describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end.) It is used in saved games.

* {{anchor|fog_override|'''[fog_override]'''}}: With keys x= and y=, this records the hexes that have been cleared (multiturn) with {{tag|DirectActionsWML|lift_fog}}.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
:This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[ShroudDataWML]].

* '''persistent''': whether the side exists in any other scenarios. If 'yes', then ''save_id'' (see below) is used to identify the side in other scenarios. Defaults to 'yes' for sides with a human controller, and 'no' for ai controlled sides.

* '''save_id''': defaults to the leader's ''id'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog.

* '''previous_save_id''': {{DevFeature1.13|2}} defaults to ''save_id''. Only used in mp games, specially mp campaigns. This attribute specifies which user should play this side by default. For example if a side has previous_save_id="Konrad" then the side will be assigned to that player who played the side with the save_id="Konrad" in the previous level. If used in the first scenario, multiple sides with the same ''previous_save_id'' will be assigned to the same player.

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''. ''team_name'' is now a comma-separated list of teams that the side is on.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''current_player''': a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username. {{DevFeature1.13|0}} This field is now always the player name (mp server nick) it impossible to change it with wml/lua. {{DevFeature1.13|5}} You can use ''side_name'' instead to specify the name for the side (which is then used in new turn dialogs, statisitc dialogs etc.)

* '''side_name''': {{DevFeature1.13|5}} a translatable string representing the name of the side, used for example in the new turn dialog. Defaults to ''name'' if the side was inside a '''[scenario]''' and to the player's name if the side was inside a '''[multiplayer]'''.

* '''color''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg. Can also be an inline color range (the rgb key from [[GameConfigWML#Color_Palettes]]).

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-[1~3].png:750''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]).

* '''village_support''': the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in ''village_support'', '''[game_config]''' ([[GameConfigWML]]).

* '''recall_cost''': the amount of gold it costs to recall a unit. Default specified in ''recall_cost'', '''[game_config]''' ([[GameConfigWML]]). {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud. {{DevFeature1.13|1}} This has been deprecated in favor of share_vision (see below).

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog). {{DevFeature1.13|1}} This has been deprecated in favor of share_vision (see below).

* '''share_vision''': {{DevFeature1.13|1}} all/shroud/none. If ''all'', both shroud and fog view will be shared by this side. If ''shroud'', only shroud view will be shared. If ''none'', the view is not shared.

* '''scroll_to_leader''': optional. If 'no', scroll to the leader is not performed on the start of each turn. (default: yes)

* '''suppress_end_turn_confirmation''': If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)

* {{anchor|ai|'''[ai]'''}}: if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* {{anchor|village|'''[village]'''}}: describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another '''[village]''' tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* {{anchor|unit|'''[unit]'''}}: describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

* {{anchor|leader|'''[leader]'''}}: describes the leader for the side, basically same as '''[unit]''' except that ''canrecruit'' will default to yes and current position to the side starting location if not specified. {{DevFeature1.17|17}} Furthermore, if left out, the '''name''' and '''save_id''' attributes in '''[side]''' will be set to the '''name''' and '''id''' attributes in the first '''[leader]''' tag.

* {{anchor|variables|'''[variables]'''}}: {{DevFeature1.19|8}} Can be used to define side variables. When you use :inspect to see the variables, they will be listed under ''team''. This tag can also be placed in '''[unit]''' and '''[leader]''', where it will create variables as part of this unit.

* {{anchor|defeat_condition|'''defeat_condition'''}}: Specifies when a side is considered ''defeated'' this is checked ''for all sides'', after every player action and at the beginning of every turn.
** '''no_leader_left''': (default) The side is considered defeated if it has no units with canrecruit=yes
** '''no_units_left''': The side is defeated as soon as it has no units left.
** '''never''': The side is never considered defeated.
** '''always''': The side is always considered defeated.

: For the meaning and significance of ''defeated'', see [[ScenarioWML#Scenario_End_Conditions]]

== Multiplayer Keys ==

These keys are only permitted in a '''[side]''' tag for a '''[multiplayer]''' scenario.

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation. False also prevents this side from being included in shuffle sides. Defaults to yes.

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''disallow_shuffle''': {{DevFeature1.13|0}} do not shuffle this side if the "shuffle sides" option is used. (Usually all playable sides are shuffled.) (default: no)

* '''chose_random''': {{DevFeature1.13|0}} indicates if a side chose a random faction during creation

* '''controller_lock''': if true then this side's controller ("Player/Type") modification is limited. It is bound to the '''controller''' attribute in [[SideWML]].

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''color_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction_lock''': if true then this side's faction is not allowed to be modified.

* '''no_leader''': if 'yes', prevents the engine from generating a leader from the multiplayer faction, basically an alias of '''leader_lock'''

* '''leader_lock''': if true then this side's leader (type or gender) is not allowed to be modified. Note that if ''type='' key is missing, ''leader_lock=yes'' means the side will have no leader.

* '''faction''': if a valid faction id is provided then this side's faction will default to it in the game setup screen. {{DevFeature1.13|?}} if this key isn't included in the ''[side]'' then a random faction will be chosen, and the side's recruit list set from the faction. To use a custom ''recruit'' list, you must also specify ''faction=Custom''.

* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.

N.B. the ''lock'' attributes use [[ScenarioWML]] '''force_lock_settings''' as their default value. I.e. if no value to ''lock'' was set, it will take '''force_lock_settings''' value.

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Template:WML Tags

2025-03-14T20:16:01Z

Shiki: add [have_side]

{| class="reference-sidebar"
|-
|
<span class="editlink">[[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit]]</span>'''[[ReferenceWML|WML Tags]]'''
|-
|''A:''
[[AbilitiesWML#The .5Babilities.5D tag|abilities]],
[[CreditsWML#.5Babout.5D|about]],
[[AchievementsWML#.5Bachievement.5D|achievement]],
[[AchievementsWML#.5Bachievement_group.5D|achievement_group]],
[[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions|add_ai_behavior]],
[[AdvancedPreferenceWML|advanced_preference]],
[[UnitTypeWML#advancefrom|advancefrom]],
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AbilitiesWML#affect_adjacent|affect_adjacent]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],
[[StandardSideFilter#allied_with|allied_with]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta-Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML#The .5Banimation.5D tag|animation]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],
attack ([[ReplayWML#attack|replay]], [[UnitTypeWML#Attacks|weapon]]),
[[AnimationWML#short-attack|attack_anim]],
attacks ([[AbilitiesWML#The_.5Bspecials.5D_tag|special]], [[StatisticalScenarioWML#The_.5Bteam.5D_tag|stats]]),
[[AiWML#avoid|avoid]];
|-
|''B:''
[[UnitTypeWML#base_unit|base_unit]],
[[IntroWML#.5Bbackground_layer.5D|background_layer]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|berserk]],
[[BinaryPathWML|binary_path]],
[[InternalActionsWML#Flow_control_actions|break]],
[[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcancel_action.5D|cancel_action]],
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]],
[[InterfaceActionsWML#.5Bchange_theme.5D|change_theme]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[OptionWML#checkbox|checkbox]],
[[OptionWML#choice|choice]],
[[ReplayWML#choose|choose]],
[[PersistenceWML#WML Syntax|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],
[[GameConfigWML#Color_Palettes|color_palette]],
[[GameConfigWML#Color_Palettes|color_range]],
command ([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),
[[InternalActionsWML#Flow_control_actions|continue]],
[[CoreWML|core]],
[[CreditsWML#.5Bcredits_group.5D|credits_group]],
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];
|-
|''D:''
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage_type]],
[[AnimationWML#short-death|death]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|default]],
[[AnimationWML#short-defend|defend]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],
[[UnitsWML#defense|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML#attack|destination]],
[[CampaignWML#difficulty|difficulty]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|disable]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]],
[[DirectActionsWML#.5Bdo_command.5D|do_command]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]],
[[AnimationWML#short-draw_weapon|draw_weapon_anim]];
|-
|''E:''
[[EditorWML#The_.5Beditor_group.5D_tag|editor_group]],
[[EditorWML#The_.5Beditor_music.5D_tag|editor_music]],
[[EditorWML#The_.5Beditor_times.5D_tag|editor_times]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#Conditional Branches|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML#end_turn|replay]]),
[[StandardSideFilter#enemy_of|enemy_of]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Engines|engine]],
entry ([[CreditsWML#.5Bentry.5D|credits]], [[OptionWML#entry|options]]),
[[EraWML|era]],
[[EventWML|event]],
[[StandardUnitFilter#filter_ability|experimental_filter_ability]],
[[StandardUnitFilter#filter_ability_active|experimental_filter_ability_active]],
[[AbilitiesWML#filter_specials|experimental_filter_specials]],
[[AnimationWML#short-extra|extra_anim]];
|-
|''F:''
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]],
[[ConditionalActionsWML#.5Bfalse.5D|false]],
[[PblWML#.5Bfeedback.5D|feedback]],
[[UnitTypeWML#variation|female]],
filter ([[FilterWML|concept]], [[EventWML#.5Bfilter.5D|event]]),
[[StandardUnitFilter#filter_adjacent|filter_adjacent]],
[[StandardLocationFilter#filter_adjacent_location|filter_adjacent_location]],
[[FilterWML#Filtering_Weapons|filter_attack]],
[[AbilitiesWML#filter_attacker|filter_attacker]],
[[AbilitiesWML#filter_base_value|filter_base_value]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[AbilitiesWML#filter_defender|filter_defender]],
[[AiWML#Filtering_Combat_with_the_attacks_Aspect|filter_enemy]],
[[StandardLocationFilter|filter_location]],
[[AbilitiesWML#filter_opponent|filter_opponent]],
[[AiWML#Filtering_Combat_with_the_attacks_Aspect|filter_own]],
[[StandardLocationFilter#filter_owner|filter_owner]],
[[StandardLocationFilter#filter_radius|filter_radius]],
[[SingleUnitWML#filter_recall|filter_recall]],
[[StandardUnitFilter|filter_second]],
[[FilterWML#Filtering_Weapons|filter_second_attack]],
[[AbilitiesWML#filter_self|filter_self]],
[[StandardSideFilter|filter_side]],
[[AbilitiesWML#filter_student|filter_student]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[FilterWML#Filtering_Weapons|filter_weapon]],
[[FilterWML#Filtering_on_WML_data|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[FontsWML|fonts]],
[[ConditionalActionsWML#.5Bfor.5D|for]],
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],
[[ConditionalActionsWML#.5Bfound_item.5D|found_item]],
[[AnimationWML#The .5Bframe.5D tag|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[PersistenceWML#WML Syntax|get_global_variable]],
[[AiWML#The_.5Bgoal.5D_Tag|goal]],
[[DirectActionsWML#.5Bgold.5D|gold]],
[[InterfaceActionsWML#objectives-gold_carryover|gold_carryover]];
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[StandardSideFilter#has_ally|has_ally]],
[[StandardUnitFilter#has_attack|has_attack]],
[[StandardSideFilter#has_unit|has_unit]],
[[ConditionalActionsWML#.5Bhas_achievement.5D|has_achievement]],
[[ConditionalActionsWML#.5Bhave_location.5D|have_location]],
[[ConditionalActionsWML#.5Bhave_side.5D|have_side]],
[[ConditionalActionsWML#.5Bhave_unit.5D|have_unit]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[AnimationWML#short-healed|healed_anim]],
[[AnimationWML#short-healing|healing_anim]],
[[AbilitiesWML#The_.5Babilities.5D_tag|heals]],
[[UnitsWML#.5Bhide_help.5D|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],
[[AbilitiesWML#The_.5Babilities.5D_tag|hides]];
|-
|''I:''
[[AnimationWML#short-idle|idle_anim]],
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#Conditional Branches|animation]], [[IntroWML|intro]]),
[[AbilitiesWML#The_.5Babilities.5D_tag|illuminates]],
image ([[IntroWML#.5Bimage.5D|intro]], [[TerrainGraphicsWML#The_.5Bimage.5D_subtag|terrain]]),
[[ReplayWML#init_side|init_side]],
[[VariablesWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[InterfaceActionsWML#.5Bitem.5D|item]],
[[EditorWML#The_.5Bitem_group.5D_tag|item_group]];
|-
|''J:''
[[UnitsWML#jamming_costs|jamming_costs]],
[[InternalActionsWML#join|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|killed]];
|-
|''L:''
[[InterfaceActionsWML#.5Blabel.5D|label]],
[[LanguageWML|language]],
[[SideWML#leader|leader]],
[[AiWML#leader_goal|leader_goal]],
[[AbilitiesWML#The_.5Babilities.5D_tag|leadership]],
[[AnimationWML#short-leading|leading_anim]],
[[AnimationWML#short-levelin|levelin_anim]],
[[AnimationWML#short-levelout|levelout_anim]],
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],
[[AI_Recruitment#instructions-limit|limit]],
[[InternalActionsWML#set_variables-literal|literal]],
[[AddonsWML#load_resource|load_resource]],
[[LocaleWML|locale]],
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],
[[LuaWML|lua]];
|-
|''M:''
[[UnitTypeWML#variation|male]],
[[SavefileWML|menu_item]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[Micro AIs|micro_ai]],
[[AnimationWML#The .5Bframe.5D tag|missile_frame]],
[[ModificationWML|modification]],
[[SingleUnitWML#modifications|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[AddonsWML#modify_unit_type|modify_unit_type]],
[[ReplayWML#move|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[AnimationWML#short-movement|movement_anim]],
[[UnitsWML#movement_costs|movement costs]],
[[UnitsWML#.5Bmovetype.5D|movetype]],
[[ScenarioWML#The_.5Bmultiplayer.5D_tag|multiplayer]],
[[EraWML#Defining_Factions|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
[[ConditionalActionsWML#Meta-Condition_Tags|not]],
[[InterfaceActionsWML#objectives-note|note]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#objectives-objective|objective]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[DirectActionsWML#.5Bon_undo.5D|on_undo]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML#.5Bmessage.5D|option]],
[[OptionWML|options]],
[[ConditionalActionsWML#Meta-Condition_Tags|or]];
|-
|''P:''
[[IntroWML#.5Bpart.5D|part]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]],
[[DirectActionsWML#.5Bpetrify.5D|petrify]],
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]],
[[AnimationWML#short-post_movement|post_movement_anim]],
[[AnimationWML#short-pre_movement|pre_movement_anim]],
[[InternalActionsWML#.5Bfire_event.5D|primary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|primary_unit]],
[[InterfaceActionsWML#.5Bprint.5D|print]],
[[DirectActionsWML#.5Bprogress_achievement.5D|progress_achievement]],
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];
|-
|''R:''
[[UnitsWML#.5Brace.5D|race]],
[[InternalActionsWML#.5Brandom_placement.5D|random_placement]],
recall ([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML#recall|replay]]),
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|recalls]],
[[ReplayWML#recruit|recruit]],
[[AnimationWML#short-recruit|recruit_anim]],
[[AnimationWML#short-recruiting|recruiting_anim]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|recruits]],
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[AbilitiesWML#The_.5Babilities.5D_tag|regenerate]],
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]],
[[DirectActionsWML#.5Bremove_object.5D|remove_object]],
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]],
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]],
[[DirectActionsWML#.5Bremove_trait.5D|remove_trait]],
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]],
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]],
[[ReplayWML|replay]],
[[SavefileWML|replay_start]],
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]],
resistance ([[AbilitiesWML#The_.5Babilities.5D_tag|ability]], [[UnitsWML#resistance|unit]]),
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],
[[ThemeWML#The_toplevel_.5Btheme.5D_tag|resolution]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],
[[InternalActionsWML#Flow_control_actions|return]],
[[InternalActionsWML#.5Brole.5D|role]],
[[TerrainMaskWML#rule|rule]];
|-
|''S:''
[[SavefileWML|save]],
[[ScenarioWML#The_.5Bscenario.5D_tag|scenario]],
[[InterfaceActionsWML#.5Bscreen_fade.5D|screen_fade]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]],
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_unit]],
[[HelpWML#section|section]],
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]],
[[ReplayWML#sequence|sequence]],
[[DirectActionsWML#.5Bset_achievement.5D|set_achievement]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[PersistenceWML#WML_Syntax|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]],
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[EffectWML#set_specials|set_specials]],
[[InternalActionsWML#.5Bset_variable.5D|set_variable]],
[[InternalActionsWML#.5Bset_variables.5D|set_variables]],
[[AnimationWML#short-sheath_weapon|sheath_weapon_anim]],
show_if ([[InterfaceActionsWML#.5Bmessage.5D|message]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]],
[[AbilitiesWML#The_.5Babilities.5D_tag|skirmisher]],
[[OptionWML#slider|slider]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]],
[[SavefileWML|snapshot]],
[[InterfaceActionsWML#.5Bsound.5D|sound]],
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]],
source ([[ReplayWML#attack|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),
[[UnitTypeWML#Special Notes|special_note]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]],
[[InternalActionsWML#set_variables-split|split]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Stages|stage]],
[[AnimationWML#short-standing|standing_anim]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[SingleUnitWML#status|status]],
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]],
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]],
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]],
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]],
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]],
[[InternalActionsWML#.5Bstore_unit_defense.5D|store_unit_defense]],
[[InternalActionsWML#.5Bstore_unit_defense_on.5D|store_unit_defense_on]],
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],
[[IntroWML|story]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]],
[[AchievementsWML#.5Bsub_achievement.5D|sub_achievement]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]],
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];
|-
|''T:''
[[DirectActionsWML#.5Btunnel.5D|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),
[[AnimationWML#short-teleport|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]],
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],
[[TerrainGraphicsWML|terrain_graphics]],
[[TerrainMaskWML|terrain_mask]],
[[TerrainWML|terrain_type]],
[[ScenarioWML#The_.5Btest.5D_tag|test]],
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],
[[TestWML#The_.5Btest_do_attack_by_id.5D_tag|test_do_attack_by_id]],
[[InterfaceActionsWML#message-text_input|text_input]],
[[GettextForWesnothDevelopers#The_textdomain_tag|textdomain]],
[[ThemeWML|theme]],
[[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML#The_.5Btile.5D_subtag|tile]],
[[TimeWML|time]],
[[DirectActionsWML#.5Btime_area.5D|time_area]],
[[HelpWML#topic|topic]],
[[HelpWML#toplevel|toplevel]],
[[UnitsWML#.5Btrait.5D|trait]],
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]],
[[InternalActionsWML#.5Bfind_path.5D|traveler]],
[[ConditionalActionsWML#.5Btrue.5D|true]],
[[DirectActionsWML#.5Btunnel.5D|tunnel]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]],
unit ([[DirectActionsWML#.5Bunit.5D|action]], [[SingleUnitWML|scenario]]),
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]],
[[UnitTypeWML|unit_type]],
[[InternalActionsWML#.5Bunit_worth.5D|unit_worth]],
[[UnitsWML|units]],
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]],
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]],
[[InternalActionsWML#.5Bunsynced.5D|unsynced]];
|-
| ''V:''
[[InternalActionsWML#set_variables-value|value]],
[[ConditionalActionsWML#.5Bvariable.5D|variable]],
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],
[[TerrainGraphicsWML#variant|variant]],
[[UnitTypeWML#variation|variation]],
[[AnimationWML#short-victory|victory_anim]],
[[SideWML#village|village]],
[[UnitsWML#vision_costs|vision_costs]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]],
[[SchemaWML|wml_schema]];
|-
| ''Z:''
[[InterfaceActionsWML#.5Bzoom.5D|zoom]];
|}<includeonly>[[Category:WML Reference]]</includeonly><noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the [[ReferenceWML|WML reference]] pages.</noinclude>

ConditionalActionsWML

2025-03-14T20:14:32Z

Shiki: /* Condition Tags */ document [have_side]

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error), use '''[for]''' instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however 1.16 does not support using the same ''variable='' name for both loops ([https://github.com/wesnoth/wesnoth/issues/6305 issue 6305], fixed in {{DevFeature1.17|13}}).

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use '''[for]''' instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [have_side] ===

{{DevFeature1.19|10}}

* [[StandardSideFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, exactly this number of sides must match the filter. Accepts only a number.

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [has_sub_achievement] ===

{{DevFeature1.17|17}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different sub-achievements completed. As such it will always be treated as if the sub-achievement is not completed.

=== [variable] ===

Test the value of a WML [[VariablesWML|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (i.e., a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event in the same scenario. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function, nor objects added in a previous scenario in a campaign.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''name''': A name used to identify the tag in error messages.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wml.variables.turn_number % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

== See Also ==
* [[SyntaxWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

InterfaceActionsWML

2025-03-05T21:14:16Z

Shiki: /* [label] */ document incompatibility between color and text with Pango markup

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>[message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will <b>not</b> work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} <b>none:</b> display no image
* '''mirror''': {{DevFeature1.13|5}} whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}} same as the '''image''' attribute, but the image is displayed on the right of the message text. {{DevFeature1.17|7}} not working anymore, but there is plan to fix it eventually https://github.com/wesnoth/wesnoth/issues/8770
* '''second_mirror''': {{DevFeature1.13|6}} same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''voice''', '''male_voice''', '''female_voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message. The gendered forms are applied the same as for '''message'''. They are never used when the speaker is the narrator - only '''voice''' is used in that case.
* {{anchor|message-option|'''[option]'''}}: No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* {{anchor|message-text_input|'''[text_input]'''}}: there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'. The full list of color names may be found in Pango's [https://github.com/GNOME/pango/blob/main/tools/rgb.txt rgb.txt] file.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

Tags of '''[objectives]''':
* {{anchor|objectives-objective|'''[objective]'''}}: describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* {{anchor|objectives-gold_carryover|'''[gold_carryover]'''}}: describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* {{anchor|objectives-note|'''[note]'''}}: describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item, defaults to "buttons/WML-custom.png"
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On <b>1.14.2</b> and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]; do not use a [filter] subtag.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''', '''[if]''', '''[switch]''', '''[wml_message]''', '''[deprecated_message]''' : See [[IntroWML]].

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music] ===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit
* '''object_id''': object id to use, defaults to the '''image''' key with an "overlay_" prefix; this allows using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']]
* '''duration''': object duration

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
* '''object_id''': object id to use
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what hex the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say. If you put an empty string <code>""</code> as an argument, the label will be completely removed. Use this method if you want to remove a specific label from any location.
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255. When you use Pango markup in the text, you cannot use this, but in that case you could colorize the text via Pango markup.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter] unless you intend to match one or more units).
* '''text''': the text to display.

The default text color is <span style="color: #6b8cff;">'''#6b8cff'''</span>. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="<span color='#cccc33'>" + _ "Your text here" + "</span>"
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. WML wrapper of [[LuaAPI/wesnoth#wesnoth.log]], see the link for more description.
* '''message''': the message to show.
* '''to_chat''': controls whether message is visible in chat, though logger=wml means message is visible anyways. Default ''no''.
* '''logger''': one of '''info''', '''debug''', '''warning''', '''error''', '''wml'''. Default ''info''.

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

ConditionalActionsWML

2025-03-05T19:22:57Z

Shiki: /* [lua] */ update Lua

{{WML Tags}}

Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside '''[if]''' aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
** [[#Condition Tags|Condition Tags]]: Specifies the conditions, just like in '''[if]'''.
** '''[then]''': Specifies actions, exactly like the '''[then]''' tag inside '''[if]'''.

* '''[else]''': Contains [[ActionWML|actions]] which should be executed if all condition tags in the '''[if]''' and any directly nested '''[elseif]''' all evaluate as false.

'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.

Example usage:
<syntaxhighlight lang=wml>
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[elseif]
[variable]
name=we.gold
equals=$they.gold
[/variable]
[then]
[message]
message=This should be fair!
[/message]
[/then]
[/elseif]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
</syntaxhighlight>

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
<syntaxhighlight lang=wml>
[switch]
variable=foo
[case]
value="A"
# ... WML if foo=A ...
[/case]
[case]
value="B"
# ... WML if foo=B ...
[/case]
[else]
# ... WML if not foo=A nor foo=B ...
[/else]
[/switch]
</syntaxhighlight>

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false. Multiple '''[do]''' tags can be used, and they will be executed in sequence on each iteration. However, there is usually no reason to do this.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros. Note: This macro is deprecated; you should just use the '''[foreach]''' WML tag instead.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [for] ===

{{DevFeature1.13|2}}

Loops over an integer range. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.

* '''variable''': The name of the variable containing the current index. Defaults to ''i''. If there is already a variable with this name, it will be automatically saved before the start of the loop, and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, it will be automatically deleted, there is no need to do a '''[clear_variable]''' afterwards
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [foreach] ===

{{DevFeature1.13|2}}

Loops over an array variable. This is not used to implement the {FOREACH} macro because [foreach] doesn't support adding or removing elements while looping (and will usually raise an error), use '''[for]''' instead.

* '''array''': The array variable to loop over.
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
* '''[do]''': The actions to execute on each iteration. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

The '''[foreach]''' tag simulates local-scoping of its index variables. If there was already a WML variable with the same name (by default ''i'' and ''this_item'' respectively), it will be automatically saved before the start of the '''[do]''', and reset to its previous value when the loop exits. If there wasn't a variable with that name before the loop, there is no need to do a '''[clear_variable]''' afterwards.

It's possible to nest '''[foreach]''' loops, however 1.16 does not support using the same ''variable='' name for both loops ([https://github.com/wesnoth/wesnoth/issues/6305 issue 6305], fixed in {{DevFeature1.17|13}}).

=== [repeat] ===

{{DevFeature1.13|2}}

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use '''[for]''' instead.)

* '''times''': The number of times to repeat the actions.
* '''[do]''': The actions to repeat. As with '''[while]''', it is possible to use multiple '''[do]''' tags, but there is usually no reason to.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

=== [true] ===

Represents a condition that always yields true. Takes no arguments.

=== [false] ===

Represents a condition that always yields false. Takes no arguments.

=== [have_unit] ===

A unit with greater than zero hit points matching this filter exists.

* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.
* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')

=== [have_location] ===

A location matching this filter exists.

* [[StandardLocationFilter]]: Selection criteria.
* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

=== [has_achievement] ===

{{DevFeature1.17|13}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

=== [has_sub_achievement] ===

{{DevFeature1.17|17}}

The specified achievement has been completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

'''NOTE:''' This is not safe to use in online multiplayer since different players can have different sub-achievements completed. As such it will always be treated as if the sub-achievement is not completed.

=== [variable] ===

Test the value of a WML [[VariablesWML|variable]] against another value.

* '''name''': The name of the variable to test.
* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
** '''contains''': ''$name'' contains this string value.
** '''equals''': ''$name'' is equal (string wise) to this value.
** '''not_equals''': ''$name'' is not equal (string wise) to this value.
** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
** '''greater_than''': ''$name'' is numerically greater than this value.
** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.
** '''less_than''': ''$name'' is numerically less than this value.
** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.
** '''boolean_equals''': ''$name'' has an equivalent boolean value.
** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.
** '''formula''': {{DevFeature1.15|0}} ''$name'' satisfies the given [[Wesnoth_Formula_Language|WFL]] formula.

====Boolean Values====
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.

* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true.

'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

====Formulas====
When using a formula, the variable's value can be referenced as '''value''' in the formula. This is a WFL representation of a config object that supports the following fields:

* '''__all_children''': A list of key-value pairs, where the key is the tag name and the value is another config object representing the tag content.
* '''__children''': A map from tag name to a list of all children with that tag name.
* '''__attributes''': A map from attribute to value. Only useful if you specifically require a map for some reason.
* ''Any attribute name'': The value of that attribute
* ''Any tag name'': A list of all children with that tag name.
* Note that if there is a tag and an attribute with the same name, accessing it by name will return the attribute. You would need to use '''__children''' to access the tag.

For example, suppose you had a variable with the following WML content:

<syntaxhighlight lang=wml>
[my_variable]
stuff=777
something=a value
[something]
value=42
[/something]
[another_tag]
value=21
[/another_tag]
[subarray]
value=8
[/subarray]
[subarray]
value=91
[/subarray]
[another_tag]
value=12
[/another_tag]
[/my_variable]
</syntaxhighlight>

Then the formula could access the following variables on the '''value''' object:
* '''__all_children''': A list of ordered key-value pairs roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> ['value' -> 42], 'another_tag' -> ['value' -> 21], 'subarray' -> ['value' -> 8], 'subarray' -> ['value' -> 91], 'another_tag' -> ['value' -> 12]]</syntaxhighlight>
* '''__children''': A map roughly equivalent to <syntaxhighlight lang=wfl inline>['something' -> [['value' -> 42]], 'another_tag' -> [['value' -> 21], ['value' -> 12]], 'subarray' -> [['value' -> 8], ['value' -> 91]]]</syntaxhighlight>
* '''__attributes''': A map equivalent to <syntaxhighlight lang=wfl inline>['stuff' -> 777, 'something' -> 'a value']</syntaxhighlight>
* '''stuff''': The number <syntaxhighlight lang=wfl inline>777</syntaxhighlight>
* '''something''': The string <syntaxhighlight lang=wfl inline>'a value'</syntaxhighlight>
* '''another_tag''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 21], ['value' -> 12]]</syntaxhighlight>
* '''subarray''': A list roughly equivalent to <syntaxhighlight lang=wfl inline>[['value' -> 8], ['value' -> 91]]</syntaxhighlight>

{{DevFeature1.17|11}} When using a formula, you can now specify an additional key:

* '''as_type''': Specifies the type of the '''value''' object in the formula. The default is ''wml'', which uses the structure as described above. The other supported options are:
** ''unit'': Interprets the variable's value as a stored unit, allowing you to write the formula the same way you would in a [[StandardUnitFilter]].
** ''weapon'': Interprets the variable's value as an attack type, allowing you to write the formula the same way you would in a [[StandardWeaponFilter]].

=== [found_item] ===

{{DevFeature1.13|2}} Test if an item (i.e., a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event in the same scenario. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function, nor objects added in a previous scenario in a campaign.

* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

=== [proceed_to_next_scenario] ===

{{DevFeature1.13|10}} In SP, true if the scenario has been won.

=== [lua] ===

{{DevFeature1.13|11}} Evaluate a lua expression, which must return a boolean value. Useful for writing one-off conditions that are difficult to express with other tags, but for much-used conditions it's better to define a custom condition tag using [[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]].

* '''code''': The Lua expression.
* '''name''': A name used to identify the tag in error messages.
* '''[args]''': Arbitrary data passed to the expression, accessible via <tt>...</tt> in the Lua code.

For example

<syntaxhighlight lang=wml>
[event]
name=new turn
first_time_only=no
[filter_condition]
[lua]
code = << return (wml.variables["turn_number"] % 2 == 0) >>
[/lua]
[/filter_condition]
[message]
speaker=narrator
message= "Hello world $turn_number|"
[/message]
[/event]
</syntaxhighlight>

=== Meta-Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
# this true or false result is combined with the top meta-condition to produce another true or false result
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.

== See Also ==
* [[SyntaxWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

EffectWML

2025-03-04T18:11:05Z

Shiki: Document set and set_total for hitpoints

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaAPI/wesnoth#wesnoth.effects]]. Some examples can be seen in [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/World_Conquest/lua/game_mechanics/effects.lua World Conquest].

[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''[remove_specials]''': {{DevFeature1.19|6}} remove the listed specials. Use [[StandardAbilityFilter]], special removed if matches. This tag is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
** '''set_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''set_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_min_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
** '''increase_max_range''' {{DevFeature1.19|4}} modify required distance between units in order to allow using attack
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''set''': the new amount of the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''set_total''': will set the unit's max HP to the specified value.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes" or the addition if "no".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

== Examples ==
=== Effect: apply_to = new_animation ===
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.

[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y = 1,5
[/filter]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]

If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable = stored_unit
[/store_unit]
[set_variables]
name = stored_unit.modifications.object
[value]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable = stored_unit
[/unstore_unit]
[/event]

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

LuaAPI/wesnoth

2024-11-25T00:28:54Z

Shiki: /* wesnoth.scenario */ era limitation

<div class="tright"> __TOC__ </div>

The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.

== Functions ==

=== wesnoth.dofile ===

* '''wesnoth.dofile'''(''file_path'', [...]) → ...

Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a ''.lua'' extension instead of ''.cfg.'' Any extra parameters to '''dofile''' are forwarded to the script (which can access them via the special <tt>...</tt> variable), and '''dofile''' returns all the values returned by the script.

=== wesnoth.require ===

* '''wesnoth.require'''(''module'') → ''module_contents''

Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by '''wesnoth.dofile'''. In addition, the ''.lua'' extension will automatically be appended if necessary. The module script is invoked with no arguments, and '''wesnoth.require''' then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the ''.lua'' extension.

'''wesnoth.require''' returns nil on failure, for example if it could not locate the module. If it did locate the module, but the module did not return anything (or returned nil), then '''wesnoth.require''' returns an empty table with a metatable that raises an error on any attempt to access it.

=== wesnoth.textdomain ===

* '''wesnoth.textdomain'''(''domain'') → ''textdomain_constructor''

Returns a callable userdata that can be used to construct translatable strings. A typical use is:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "example"
wesnoth.alert(_ "This is an example translated string!")
</syntaxhighlight>

The full syntax for using the result of this function is:

* ''textdomain_constructor''(''string'', [''string_plural'', ''number'']) → ''translatable_string''

By passing the optional arguments, you can vary the string based on a number that will be substituted into it. As with all Lua functions, the parentheses are optional when passing a single string argument, as in the above example. This plural syntax returns a form of the string that's grammatically suitable for the indicated number, but doesn't actually substitute the number in – you need to do that yourself with either '''string.format''' or '''stringx.vformat'''.

The returned translatable string can be treated in many ways like a regular string. Translatable strings can be compared with other translatable strings or concatenated with each other or with regular strings or integers. The length operator also works, though it should be noted that its value may change if the language is changed. If you need to pass a translatable string to a function that doesn't understand them, it can be converted to a regular string with tostring.

=== wesnoth.log ===

* '''wesnoth.log'''([''logger''], ''message'', ''in_chat'')

Logs a message to the console. These messages are normally not visible unless Wesnoth is run from the command-line or (in Windows) with the --wconsole switch. The in_chat argument, however, can be set to true to also echo the message to the in-game chat area.

''logger'' is the log level.

In any context, ''logger'' can be the standard log levels of '''info''', '''debug''', '''warning''', or '''error'''. Various abbreviations of the standard four are also recognised. The default logger is '''info'''.

In the game context, you can also set the ''logger'' to '''wml'''. The '''wml''' log level is special and is intended for WML errors; it always goes to chat, so the in_chat argument is ignored and can be omitted.

The logdomain to enable these logs depends on the context. In the game context, they are written to the '''wml''' logdomain. In other contexts, the logdomain is '''scripting/lua/user'''.

=== wesnoth.as_text ===

{{DevFeature1.15|10}}

* {{LuaGameOnly}} '''wesnoth.as_text'''(''value1'', ''value2'', ...)

Accept one or more values as arguments and returns them as a string. This is intended for use as an easy way to view the contents of lua tables. Using the returned string for any other purpose is not supported.

{{DevFeature1.17|0}} This is now available in all contexts.

=== wesnoth.simulate_combat ===

* {{LuaGameOnly}} '''wesnoth.simulate_combat'''(''attacker'', [''attacker_weapon_index''], ''defender'', [''defender_weapon_index'']) → ''attacker stats evaluation'', ''defender stats evaluation'', ''attacker weapon evaluation'', ''defender weapon evaluation''

Computes the hitpoint distribution and status chance after a combat between two units. The first unit is the attacker. The attacker does not have to be on the map, but its location should be meaningful - that is, it can be a private-to-Lua clone of a unit with the '''x''' and '''y''' values changed, but whatever it is it has to have '''x''' and '''y''' values that allow attacking the defender (with '''max_range''' of the attack set appropriately it's possible to simulate attacking non-adjacent units). The second unit is the defender; it has to be on the map.

Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) and not the attack definition.

The function returns four tables describing the evaluation of the combat. The first two contain an evaluation of the combatant's stats over the course of the fight, while the second two contains more detailed information on their weapons.

The stats evaluation tables contain the following keys:

* ''stats''.'''poisoned''' → ''probability''
* ''stats''.'''slowed''' → ''probability''
* ''stats''.'''untouched''' → ''probability''

The probability that the unit will be poisoned or slowed, or that it will survive with no damage taken. (A scenario where the unit's hitpoints increase counts as untouched.)

* ''stats''.'''average_hp''' → ''number''

The expected value of the unit's hitpoints after the fight.

* ''stats''.'''hp_chance''' → ''mapping of hp to probability''

The probability that the unit's hitpoints will be at a specific value after the fight. Though it looks almost like an array, it begins at index 0 unlike a typical Lua array. Thus, it's better understood as an associated mapping from the resulting hitpoints value to the probability of ending the combat with that value. Therefore, the value at index 0 represents the chance that the unit will die.

The weapon evaluation tables contain the following keys:

{| class="wikitable"
!Key !!Description
|-
|attack_num
| DEPRECATED (use '''number'''). Attack number (0 based, -1 for no attack).
|-
|chance_to_hit
|Effective chance to hit as a percentage (all factors accounted for).
|-
|damage
|Effective damage of the weapon (all factors accounted for).
|-
|drains
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|drains]] opponent when it hits.
|-
|drain_constant
|Base HP drained regardless of damage dealt.
|-
|drain_percent
|Percentage of damage recovered as health.
|-
|firststrike
|Attack has [[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]] special.
|-
|name
|Name (not description) of the attack.
|-
|number
|Attack number (1 based, 0 for no attack).
|-
|num_blows
|Effective number of blows (takes [[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]] into account).
|-
|petrifies
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]] opponent when it hits.
|-
|plagues
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|turns opponent into a zombie]] when fatal.
|-
|plague_type
|The [[AbilitiesWML#Extra_keys_used_by_the_.5Bplague.5D_special|plague type]] used by the attack, if any.
|-
|poisons
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|poisons]] opponent when it hits.
|-
|rounds
|[[AbilitiesWML#The_.5Bspecials.5D_tag|Berserk]] special can force us to fight more than one round.
|-
|slows
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|slows]] opponent when it hits.
|}

<syntaxhighlight lang='lua'>
local function display_stats(n, t)
wesnoth.interface.add_chat_message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def, def_weapon)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)
wesnoth.interface.add_chat_message(string.format(
"The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",
att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))
</syntaxhighlight>

=== wesnoth.name_generator ===

* '''wesnoth.name_generator'''('''"markov"''', ''definition'', [''chain_size'', [''max_length'']]) → ''generator function''
* '''wesnoth.name_generator'''('''"cfg"''', ''definition'') → ''generator function''
* ''generator function''() → ''random name''

Constructs a name generator for use in generating names using either the Markov chain algorithm used in older versions of Wesnoth or the context-free grammar generator used since 1.13.5. The type parameter indicates which algorithm to use (either markov or cfg). The definition can be a string, just like it would be in a config file, or it can be formatted as a table. Additional parameters may be passed, depending on the type of generator. The function returns a callable userdata, which will return a new name each time it is called (with no parameters).

* '''Markov chain''': A Markov chain generator works by analyzing a list of input names and noticing tendencies in the way the letters are strung together. It can then apply those tendencies to produce new similar names that were not in the original list. Longer lists give better results. The definition is a list of names, formatted either as a comma-separated string or as an array-like table. The Markov generator can take two additional parameters.
** ''chain_size'': A value greater than 1 for the ''chain_size'' causes the analyzer to consider the words in chunks, which is similar to analyzing them syllable by syllable instead of letter by letter. The default chain size is 2, meaning that the analyzer treats words as consisting of 2-character syllables.
** ''max_length'': Places a cap on the total length of the name. The default value is 12 characters.
<syntaxhighlight lang=lua>
local markov_names = wesnoth.name_generator('markov', {'Kaasa', 'Kayya', 'Keyya', 'Kiira', 'Korra'}, 1)
print(markov_names(), markov_names(), markov_names())
</syntaxhighlight>
* '''Context-free grammar''': A [[context-free grammar]] is a way of specifying how strings can be constructed. The definition may be specified as a multi-line string, just as described in the preceding link, or it can be formatted as a table where the keys are non-terminals and the values are what they expand to. The expansion of each non-terminal can be formatted either as a |-separated list as described in the preceding link, or as an array-like table. (Mixing the two forms is permissible too.) The context-free generator has no additional parameters.
<syntaxhighlight lang=lua>
local cfg_names = wesnoth.name_generator('cfg', {
main = {'{prefix}{suffix}', '{prefix}{centre}{suffix}'},
prefix = 'Kaa|Ka|Ke|Kuu|Ko',
suffix = 'sa|yya|ra|rra',
centre = 'err|aash|eez|azz'
})
print(cfg_names(), cfg_names(), cfg_names())
</syntaxhighlight>

'''Note''': If you want to generate a name using any of the default generators, you can use the predefined generators in the [[LuaAPI/types#race|race]] instead of constructing one with this function.

=== wesnoth.compile_formula ===

* '''wesnoth.compile_formula'''(''formula'') → ''compiled formula''

Compiles a [[Wesnoth Formula Language]] formula into a Lua callable userdata. A compiled formula can be converted back to valid code using the built-in <code>tostring</code> function.

=== wesnoth.eval_formula ===

* '''wesnoth.eval_formula'''(''formula'', [''variables'']) → ''result''
* ''compiled formula''([''variables'']) → ''result''

Evaluate a [[Wesnoth Formula Language]] formula and return the result it computed (which can be '''nil''').

The passed in variables can be an arbitrary Lua table, which defines variables available to the formula. Unlike with WML tables, there is no restriction on the format of this table. The formula can access the variables as a list using the special WFL variable '''__list''', or as a map using the special WFL variable '''__map'''. Directly accessing keys on the table is also possible.

It is also possible to pass a unit proxy as the variables, which evaluates the formula in that unit's context just as if it had been used in a [[StandardUnitFilter]].

When calling '''wesnoth.eval_formula''', the first argument may either be an already-compiled formula or a string, in which case it will be automatically compiled on the fly.

<syntaxhighlight lang=lua>
local f = wesnoth.compile_formula('if(x > y, x - y, x + y)')

print(f{x=1,y=2}) -- prints 3.0
print(f{x=1,y=3}) -- prints 4.0
print(f{x=2,y=3}) -- prints 5.0
print(f{x=1,y=1}) -- prints 2.0
print(f{x=3,y=1}) -- prints 2.0
print(f{x=3,y=2}) -- prints 1.0
</syntaxhighlight>

=== wesnoth.version ===

* '''wesnoth.version'''(''version string'') → ''version''
* '''wesnoth.version'''(''major'', [''minor'', [''patch'']], [''suffix'')) → ''version''

Creates a version object, either by parsing a string or by building it from its component parts. The resulting version object can be compared with other version objects using the standard Lua comparison operators, which follows the same rules as the [[PreprocessorRef#.23ifver_and_.23ifnver|#ifver]] preprocessor statement. It can also be decomposed by accessing the following keys on the object:

* ''integer'': Grab any integer version component by index. A non-canonical version may have more than three components.
* '''major''': The major version number (index 1).
* '''minor''': The minor version number (index 2).
* '''revision''': The patch revision number (index 3).
* '''is_canonical''': True if the version has at most three components (plus an optional suffix).
* '''sep''': The character that separates the version components from the suffix (usually either + or nil).
* '''special''': The version suffix, for example the "dev" in "1.15.14+dev".

The version can be converted to a string using the built-in '''tostring''' function.

<syntaxhighlight lang=lua>
local function version_is_sufficient(required)
return wesnoth.current_version() >= required
end
local required = wesnoth.version "1.9.6"
if not version_is_sufficient(required) then
gui.alert(string.format("Your BfW version is insufficient, please get BfW %s or greater!", tostring(required)))
end
</syntaxhighlight>

=== wesnoth.current_version ===

* '''wesnoth.current_version'''() → ''current version''

Returns the current version of Wesnoth as a version object.

=== wesnoth.ms_since_init ===

* '''wesnoth.ms_since_init'''() → ''milliseconds''

This function returns the amount of milliseconds that have passed since Wesnoth started up the current session. Its only use is to track the passage of real time.

'''WARNING:''' this function uses the same code as [set_variable] time=stamp, and so it is MP-unsafe. It is provided only for benchmark purposes and AI development, although it should work inside wesnoth.synchronize_choice() as well.

=== wesnoth.deprecated_message ===

* '''wesnoth.deprecated_message'''(''element_name'', ''level'', ''version'', ''detail_message'')

Displays a deprecation warning in the Lua console. The level is an integer from 1 to 4 inclusive (see [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|deprecation levels]]), and the version can be left nil for levels 1 and 4. Otherwise it must be a version ''string'' (not a version object from [[#wesnoth.version|wesnoth.version]]).

=== wesnoth.deprecate_api ===

* '''wesnoth.deprecate_api'''(''original_name'', ''new_name'', ''level'', ''version'', ''element'', ''detail_message'') → ''deprecated wrapper''

Creates a deprecated wrapper for a function or table. A deprecated function will raise the deprecated message the first time it's called, and then suppress it thereafter. A deprecated table will raise the deprecated message the first time a key is read or assigned, and then suppress it thereafter.

The ''element'' is the function or table to wrap. It can be the original function or the new function (which may happen if the function was renamed without any interface changes), or a wrapper function that calls the new function while providing the interface of the old function. The ''level'' and ''version'' are as in [[#wesnoth.deprecated_message|wesnoth.deprecated_message]].

If ''level'' is 4, then the ''element'' is ignored (you can pass '''nil''') and a generic deprecated wrapper is returned that does nothing but raises the deprecated message the first time you call it, assign a key, or read a key, and suppresses it thereafter. This is intended for a function that was removed without deprecation, to leave behind a more informative message if someone still attempts to use it.

If Wesnoth is run with the <tt>--strict-lua</tt> command-line option, this function will return '''nil''' instead of the deprecated wrapper. Since the normal use-case of this function is to assign the deprecated wrapper to the original name, this has the effect of erasing any deprecated functions from the API.

The result of this function always contains a '''__deprecated''' attribute set to true, which can allow identifying if something is deprecated.

=== wesnoth.type ===

{{DevFeature1.17|?}}

* '''wesnoth.type'''(''value'') → ''type name''

Returns a string describing the value's type. This is the same as the built-in type function, except that it returns a more specific string in the case of userdata or tables, based on the metatable. For example, it would return 'unit' if called on a unit.

=== wesnoth.named_tuple ===

{{DevFeature1.17|?}}

* '''wesnoth.named_tuple'''(''array'', ''names'') → ''named tuple''

Decorates a numeric based array so that the indices can be accessed by name instead of by index. This function is used internally for a number of things, most notably map locations and WML tags. Most end-users will not need to use it, but it could be useful if you wish to build a Lua API that returns locations (or similar data) in the engine-standard format.

For example:

<syntaxhighlight lang=lua>
local t = wesnoth.named_tuple({42,21,36}, {'x', 'y', 'z'})

print(t[1]) -- prints 42
print(t[2]) -- prints 21
print(t[3]) -- prints 36
print(t.x) -- prints 42
print(t.y) -- prints 21
print(t.z) -- prints 36
</syntaxhighlight>

=== wesnoth.get_language ===

* '''wesnoth.get_language'''() → ''string''

Gets the language the UI is currently set to. Note that this may return an empty string if using the system default language.

=== wesnoth.print_attributes ===

* '''wesnoth.print_attributes'''(''object'', [''function''])

Prints out a list of attributes that can be accessed on the object, excluding deprecated functionality. The function defaults to '''print''', and receives a formatted line usually containing multiple attributes. They are annotated by type – &fnof; for a function, &dagger; for a table, ! if there was an error attempting to determine the type (which includes write-only attributes). Other types are unannotated.

For tables, by default this iterates the table using '''pairs''' to discover the attributes available, walking the metatable hierarchy if there is an '''__index''' table and filtering out anything that contains a '''__deprecated''' attribute set to '''true'''. However, if finds a function as the '''__index''', and the table's metatable also has a member '''__dir''', it will be used instead. The '''__dir''' can either be an array of strings, or a function that returns an array of strings. It will automatically be sorted and have any duplicates filtered out.

For custom objects defined by the engine, there is special handling so that this function shows the correct result. For example, if used on a GUI2 widget object, it will show the attributes available for that type of widget, as well as the IDs of any sub-widgets that can be accessed by name.

In the Lua console only, this function can also be referenced by a shorter alias, '''dir'''.

== Hooks ==

=== wesnoth.persistent_tags ===

* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''read''' ↔ '''function'''(''wml content'')
* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''write''' ↔ '''function'''(''add_tag_function'')

This is an associative table defining tags that should be persisted in saved games. Each tag is itself a table containing two functions, read and write. The write function is called in <tt>on_load</tt> and passed a function as a parameter which takes a WML table and adds it to the saved game under the specified tag; the read function is called once per matching tag found in the saved game, and is passed a WML table of its contents. Note the asymmetry here: if you're saving an array, the write function is responsible for saving the entire array (and is only called once), while the read function is only responsible for loading one item (and is called several times).

Example:

<syntaxhighlight lang=lua>
local inventory = {}

function wesnoth.persistent_tags.inventory.read(cfg)
inventory[cfg.side] = cfg
end

function wesnoth.persistent_tags.inventory.write(add)
for i = 1, #wesnoth.sides do
add(inventory[i])
end
end
</syntaxhighlight>

Notice that you don't need to create <tt>wesnoth.persistent_tags.inventory</tt> as an empty table first; you can simply define the read and write functions.

=== wesnoth.wml_actions ===

* {{LuaGameOnly}} '''wesnoth.wml_actions'''.''action'' ↔ '''function'''(''wml parameters table'')

This is a hook table that exposes and defines WML actions. Each function in this table corresponds to a single ActionWML tag, allowing you to invoke tags, define custom tags, and even modify the behavior of built-in tags. The single argument to these functions is a WML table, the content of the tag.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or wml.error "[freeze_unit] expects an id= attribute."
local unit = wesnoth.units.get(unit_id)
if unit then unit.moves = 0 end
wesnoth.units.modify({ id = unit_id }, { moves = 0 })
end
</syntaxhighlight>

The new tag can now be used in plain WML code.

<syntaxhighlight lang=wml>
[freeze_unit]
id=Delfador
[/freeze_unit]
</syntaxhighlight>

You can override functions already assigned to the table. This is useful if you need to extend functionality of core tags. For instance, the following script overrides the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.print(cfg)
local modified_cfg = setmetatable({}, {__index = cfg})
modified_cfg.size = (cfg.size or 12) + 10
wesnoth.wml_actions.print(modified_cfg)
end
</syntaxhighlight>

An action handler should be able to handle being called with either a WML table or a WML vconfig userdata. It is recommended to pass the argument through ''wml.tovconfig'' before doing anything with it, both in the action's definition and when calling it directly (in case its definition did not do that). The engine always passes a vconfig when calling a WML action.

=== wesnoth.wml_conditionals ===

* {{LuaGameOnly}} '''wesnoth.wml_conditionals'''.''action'' ↔ '''function'''(''wml parameters table'') → ''boolean result''

This is a hook table like wesnoth.wml_actions. You can use it to define new ConditionalWML tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when [[../wml#wml.eval_conditional|'''wml.eval_conditional''']] is run.

Use it like this:

<syntaxhighlight lang=lua>
function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or wml.error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end
</syntaxhighlight>

If this lua code is executed, it would make the following syntax be valid WML in your add-on:

<syntaxhighlight lang=wml>
[if]
[foo]
bar = $X
[/foo]
[then]
[message]
# ...
[/message]
[/then]
[/if]
</syntaxhighlight>

Note that the basic logic tags of ConditionalWML (true, false, and, or, not) do not pass through this table and cannot be overridden.

=== wesnoth.effects ===

* {{LuaGameOnly}} '''wesnoth.effects'''.''name'' ↔ '''function'''(''unit'', ''wml table'')
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ ''description''
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ '''function'''(''unit'', ''wml table'') → ''description''

This table contains the implementation of [[EffectWML|[effect]]]s. Each value is a callable value that takes a unit and the effect config. It can be a function or a callable table. If it is a callable table, its metatable may have a '''__descr''' field which is either a string or a function. Built-in effects are present in this table, and you may register your own custom effects too.

<syntaxhighlight lang='lua'>
function wesnoth.effects.min_resistance(u, cfg)
local resistance_new = {}
local resistance_old = wml.parsed(wml.get_child(cfg, "resistance"))
for k,v in pairs(resistance_old) do
if type(k) == "string" and type(v) == "number" and u:resistance_to(k) >= v then
resistance_new[k] = v
end
end
wesnoth.effects.resistance(u, {
apply_to = "resistance",
replace = true,
T.resistance (resistance_new),
})
end
</syntaxhighlight>

The code above adds a new <code>min_resistance</code> effect that will set the resistances to specific values if they are currently below that value. It can then be used like this (for example, in [[DirectActionsWML#.5Bobject.5D|[object]]]):

<syntaxhighlight lang='wml'>
[effect]
apply_to=min_resistance
[resistance]
cold=50
[/resistance]
[/effect]
</syntaxhighlight>

Note that in order work properly, effects must be registered before any units are created. This means it must be placed into a global or scenario level [lua] tag. In particular, the preload event is too late.

You can also specify description modifiers, which will be used if a custom effect is placed in a <code>[trait]</code> tag. Instead of setting a function as the effect, you set a table with a <code>__call</code> metafunction which does what the function would have done. The table can then have an additional <code>__descr</code> metafunction which updates descriptions as necessary. The built-in effects all use this structure. This metafunction takes the same arguments as the regular effect function, but should not modify the unit. Instead, it returns a string to be appended to the trait's effect description.

=== wesnoth.micro_ais ===

* {{LuaGameOnly}} '''wesnoth.micro_ais'''.''ai_name'' ↔ ''function''(''cfg'') → ''required'', ''optional'', ''ca_params''

Registers a new [[Micro_AIs#Custom_Micro_AIs|MicroAI]] with '''ai_type'''=''ai_name''. The function will be called by the [micro_ai] tag to set up the AI. See the link for more details on how this works.

=== wesnoth.custom_synced_commands ===

* {{LuaGameOnly}} '''wesnoth.custom_synced_commands'''.''command_name'' ↔ ''function''(''cfg'')

Registers a custom synced command, which can be invoked by AI to enable unusual behaviour. The command can do basically anything, and is guaranteed to run on all clients. The WML table passed to the callback is the same table passed to [[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]].

== Data ==

Access to most of the game data is available via various tables in the <tt>wesnoth</tt> module.

=== wesnoth.colors ===

{{DevFeature1.15|4}}

* {{LuaGameOnly}} '''wesnoth.colors'''.''color_name'' → ''color info''

Access defined [[GameConfigWML#Color_Palettes|color ranges]]. This can be used to translate the color name available from '''wesnoth.sides[n].color''' to RGB values.

Each color info table contains the following keys:

* '''mid''' - average shade for recoloring with the team color
* '''min''' - minimum shade for recoloring with the team color (this is likely to be black)
* '''max''' - maximum shade for recoloring with the team color (this is likely to be almost white)
* '''minimap''' - representative color to use on the mini-map
* '''pango_color''' - {{DevFeature1.15|13}} a hex string such as '''#ff0000''' suitable for use in formatted text

Each of '''mid''', '''min''', '''max''' and '''minimap''' have the following keys:

* '''r''' - red component of that color
* '''g''' - green component of that color
* '''b''' - blue component of that color
* '''a''' - alpha component of that color (probably fully opaque)

Reference usage in mainline: see data/multiplayer/eras.lua

=== wesnoth.current ===

Contains various information about the current game and event state.

* {{LuaGameOnly}} '''wesnoth.current.side''' → ''side number''

The number of the currently active side.

* {{LuaGameOnly}} '''wesnoth.current.turn''' → ''turn number''

The current turn number.

* {{LuaGameOnly}} '''wesnoth.current.synced_state''' → ''state''

Allows you to determine whether the current code runs in a synced context. Returns one of the following strings:

:* '''synced''' - The current code runs on all mp clients. This is the normal context, in which all gamestate changing actions should take place.
:* '''unsynced''' - The current code runs only on the local machine, so changing the gamestate here will cause out-of-sync errors. For example, during '''select''' events or during the calculation of a [[LuaAPI/wesnoth/interface#wesnoth.interface.game_display|game_display]] hook. Typical things to do here are UI related things, or entering the synced state via '''[do_command]'''.
:* '''local_choice''' - The current code was invoked by [[#wesnoth.synchronize_choice|synchronize_choice]] and runs only on one local client to calculate the return value for the choice. You cannot enter the synced context with '''[do_command]''' now.
:* '''preload''' - We are currently running a preload event or an even earlier event. This behaves similar to '''local_choice'''.

* {{LuaGameOnly}} '''wesnoth.current.user_can_invoke_commands''' → ''boolean''

Indicates whether the player is currently able to take actions in the game.

* {{LuaGameOnly}} '''wesnoth.current.map''' → ''map userdata''

The current active game map. See [[LuaAPI/types/map]] and [[LuaAPI/wesnoth/map]] for information on how this data can be used.

* {{LuaGameOnly}} '''wesnoth.current.schedule''' → ''schedule userdata''

The current global time schedule. This is a special object with the following properties:

:* #''schedule''
:The Lua length operator will return the number of turns in the schedule.

:* ''schedule''[''index''] ↔ ''time of day info''
:Get the information for a particular time of day, or replace it with new info.

:* ''schedule''.'''time_of_day''' ↔ ''id''
:Get the ID of the current active time of day, or switch to a new one. If the time of day occurs more than once in the schedule, the time will be set to the first occurrence.

:* ''schedule''.'''liminal_bonus''' ↔ ''bonus''
:Get the maximum bonus for liminal units in the current schedule. You can also override the default by assigning a different value, or revert to the default by assigning nil.

* {{LuaGameOnly}} '''wesnoth.current.event_context''' → ''WML table''

Contains information on the current active event. Returns a table with the following keys:

:* '''name''' - The event name. This is the actual event that fired, not the name in the [event] tag, so it never contains commas or variables.
:* '''id''' - The event's unique ID, if it has one.
:* '''weapon''' - The first weapon relevant to the event, if any.
:* '''second_weapon''' - The second weapon relevant to the event, if any.
:* '''damage_inflicted''' - The damage inflicted in the event, if applicable.
:* '''x1''', '''y1''' - The first location relevant to the event, if any.
:* '''x2''', '''y2''' - The second location relevant to the event, if any.
:* '''unit_x''', '''unit_y''' - The location of the first unit relevant to the event, if any. This is the same as '''x1''', '''y1''' in most cases. Currently the only exceptions are enter and exit hex events.
:* '''data''' - {{DevFeature1.17|6}} The event data. Can contain anything at all if the event was fired by [[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]]. In a village capture event, '''owner_side''' will contain the former owner of the village.

=== wesnoth.game_config ===

Contains static global information about the game. Some of this information can also be modified on the fly, but only in the game context, not in the plugin or map generator context.

* '''wesnoth.game_config.base_income''' ↔ ''integer''
* '''wesnoth.game_config.village_income''' ↔ ''integer''
* '''wesnoth.game_config.village_support''' ↔ ''integer''
* '''wesnoth.game_config.poison_amount''' ↔ ''integer''
* '''wesnoth.game_config.rest_heal_amount''' ↔ ''integer'
* '''wesnoth.game_config.recall_cost''' ↔ ''integer''
* '''wesnoth.game_config.combat_experience''' ↔ ''integer''
* '''wesnoth.game_config.kill_experience''' ↔ ''integer''

Values of various game settings.

* '''wesnoth.game_config.global_traits'''[''trait id''] →

A table with named fields (trait id strings) holding the wml tables defining the traits. This contains all global traits the engine knows about, but race-specific traits are not included. The known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].

<syntaxhighlight lang=lua>
print(wesnoth.game_config.global_traits.strong.male_name)
</syntaxhighlight>

* {{LuaGameOnly}} '''wesnoth.game_config.do_healing''' ↔ ''boolean''

Whether healing will occur at the beginning of each side's turn.

* {{LuaGameOnly}} '''wesnoth.game_config.theme''' ↔ ''theme id''

The currently active in-game theme.

* '''wesnoth.game_config.debug''' → ''boolean''

Whether debug mode is currently active. Debug mode is activated by the --debug command-line parameter or the :debug in-game command.

* '''wesnoth.game_config.debug_lua''' → ''boolean''

Whether Lua debug is enabled. Lua debug is activated by the --debug-lua command-line parameter. This does not seem to do anything by default.

* '''wesnoth.game_config.mp_debug''' → ''boolean''

Whether MP debug is enabled. MP debug is activated in the same way as debug mode, but is only active in multiplayer games.

* '''wesnoth.game_config.strict_lua''' → ''boolean''

Whether strict Lua mode is enabled. Strict Lua mode is activated by the --strict-lua command-line parameter and causes all deprecated Lua APIs to be completely removed from the engine.

* {{DevFeature1.19|4}} '''wesnoth.game_config.palettes'''.''palette'' → ''list of colors''

Returns the color palette with the given name, as defined by a '''[color_palette]''' tag in the [[GameConfigWML#Color_Palettes|game config]].

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale''' → ''list of colors''

Returns the gradient used for health bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale_text''' → ''list of colors''

Returns the gradient used for health numbers.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale''' → ''list of colors''

Returns the gradient used for experience bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale_text''' → ''list of colors''

Returns the gradient used for experience numbers.

=== wesnoth.races ===

* {{LuaGameOnly}} '''wesnoth.races'''.''id'' → ''race info''

Access defined [[UnitsWML#.5Brace.5D|races]]. Returns a [[LuaAPI/types#Race|race userdata]].

=== wesnoth.scenario ===

Contains information about the current scenario

* {{LuaGameOnly}} '''wesnoth.scenario.turns''' ↔ ''turn limit''

The current turn limit of the scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.next''' ↔ ''scenario id''

The ID of the scenario to transition to when this scenario ends.

* {{LuaGameOnly}} '''wesnoth.scenario.id''' → ''scenario id''

The ID of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.name''' →

The name of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.defeat_music''' ↔ ''list of music tracks''

The music to play if you lose this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.victory_music''' ↔ ''list of music tracks''

The music to play if you win this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.show_credits''' ↔ ''boolean''

Whether credits should be shown when this scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text''' ↔ ''text''

The end text to show when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text_duration''' ↔ ''duration''

How long to show the end text for when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.difficulty''' → ''difficult''

The difficulty level this scenario is being played on.

* {{LuaGameOnly}} '''wesnoth.scenario.type''' → ''tag name''

The type of this scenario. One of the strings '''scenario''', '''multiplayer''', or '''test'''.

* {{LuaGameOnly}} '''wesnoth.scenario.era''' → ''era tag''

The [era] tag active in this scenario. Accessing this will throw an error in single-player games. This exists only for players which have the era installed, so for an era with ''require_era=yes'' it is save to use.

* {{LuaGameOnly}} '''wesnoth.scenario.campaign''' → ''campaign tag''

The [campaign] tag active in this scenario. Accessing this will throw an error in multiplayer or test games, so be sure to check '''wesnoth.scenario.type''' first in generic code.

* {{LuaGameOnly}} '''wesnoth.scenario.resources''' → ''list of resource tags''

A list of [resource] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.modifications''' → ''list of modification tags''

A list of [modification] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.mp_settings''' → ''table''

In a multiplayer game, this is a proxy table which gives read only access to all MP-only configuration options which appear as attributes of [multiplayer] tag in a save game file. This allows accessing basically everything that can be set in the create game screen. The following keys exist in the returned table:

* '''active_mods''' - A list of all active modification IDs
* '''hash''' - A hash of mp data
* '''mp_campaign''' - Name of mp campaign
* '''mp_scenario''' - ID of this mp scenario
* '''mp_scenario_name''' - Name of this mp scenario
* '''scenario''' - MP lobby title
* '''difficulty_define''' - The campaign difficulty string for an mp campaign
* '''mp_village_gold'''
* '''mp_village_support'''
* '''mp_num_turns'''
* '''mp_era''' - The id of the chosen era
* '''mp_eras''' - A list of all era ids
* '''mp_fog'''
* '''mp_shroud'''
* '''mp_random_start_time'''
* '''experience_modifier'''
* '''mp_use_map_settings'''
* '''mp_countdown''' - Whether the timer is enabled
* '''mp_countdown_action_bonus'''
* '''mp_countdown_init_time'''
* '''mp_countdown_reservoir_time'''
* '''mp_countdown_turn_bonus'''
* '''observer'''
* '''shuffle_sides'''
* '''savegame''' - Whether this is a reloaded game
* '''side_users''' - List of how sides are assigned to users (at game start)

=== wesnoth.terrain_types ===

{{DevFeature1.15|12}}

* {{LuaGameOnly}} '''wesnoth.terrain_types'''[''code''] → ''terrain info''

Access defined [[TerrainWML|terrain types]] by their terrain code. Returns a table with the following keys:

* '''id'''
* '''name'''
* '''editor_name'''
* '''description'''
* '''icon'''
* '''editor_image'''
* '''light'''
* '''village'''
* '''castle'''
* '''keep'''
* '''healing'''

=== wesnoth.unit_types ===

* {{LuaGameOnly}} '''wesnoth.unit_types'''[''id''] → ''unit type info''

Access defined [[UnitTypeWML|unit types]] by their ID. Returns a [[LuaAPI/types#Unit_Type|unit type userdata]].

== Submodules ==

The <tt>wesnoth</tt> module also contains a number of submodules for working with particular aspects of the game.

=== wesnoth.audio ===

A [[LuaAPI/wesnoth/audio|submodule]] containing functions for playing music and sound effects.

=== wesnoth.achievements ===

A [[LuaAPI/wesnoth/achievements|submodule]] containing functions for working with in-game achievements.

=== wesnoth.game_events ===

A [[LuaAPI/wesnoth/game_events|submodule]] containing functions for working with event handlers.

=== wesnoth.map ===

{{DevFeature1.15|11}}

A [[LuaAPI/wesnoth/map|submodule]] containing functions for querying and manipulating the game map.

=== wesnoth.interface ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/interface|submodule]] containing functions pertaining to the in-game UI.

=== wesnoth.paths ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/paths|submodule]] containing functions related to pathfinding.

=== wesnoth.schedule ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/schedule|submodule]] containing functions to manipulate the time of day schedule.

=== wesnoth.sides ===

{{DevFeature1.15|3}}

A [[LuaAPI/wesnoth/sides|submodule]] containing functions for manipulating the sides of a scenario.

=== wesnoth.sync ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/sync|submodule]] containing functions to deal with multiplayer synchronization.

=== wesnoth.units ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/units|submodule]] containing functions to manipulate units on the map.

[[Category: Lua Reference]]

== Unsupported Functions ==

The following functions exist in the '''wesnoth''' module but are not intended to be used:

* wesnoth.allow_undo
* wesnoth.cancel_action
* wesnoth.clear_menu_item
* wesnoth.set_menu_item
* wesnoth.kernel_type
* wesnoth.log_replay
* wesnoth.print
* wesnoth.redraw
* wesnoth.add_known_unit
* wesnoth.get_era
* wesnoth.get_resource

Some of these have WML equivalents, so if you need the functionality you should call the WML action directly (via [[#wesnoth.wml_actions|wml_actions]] or [[LuaAPI/wml#wml.fire|wml.fire]]). Others are internal functionality used in core Lua scripts, which are not intended for general use. These functions ''may'' be removed or changed without warning or going through a deprecation cycle.

Examination of the '''wesnoth''' module will also reveal two additional subtables - the '''package''' table, which is where packages loaded by [[#wesnoth.require|wesnoth.require]] persist (meaning you can force '''wesnoth.require''' to reload a file by nulling out its entry in this table), and the '''experimental''' module, which contains functions that are available for use but without warranty - they may change without warning or going through a deprecation cycle. Use of both of these tables is unsupported.

Description/pl

2024-11-13T02:08:49Z

Shiki: adjust numbers

{{Translations}}

Ostatnia edycja: 16 stycznia 2014

== Czym jest Bitwa o Wesnoth? ==

Bitwa o Wesnoth to turowa strategia w klimatach fantasy.

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.6-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.6-4-175.jpg]
<div class="thumbcaption">Screen z rozgrywki</div></div>
</div>
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.6-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.6-1-175.jpg]
<div class="thumbcaption">Menu gry z wersji 1.11.6 </div></div>
</div>

Stwórz wspaniałą armię, stopniowo rozwijając rekrutów w doświadczonych żołnierzy. W późniejszych grach przywołuj najlepszych wojowników, aby stworzyć niszczycielską drużynę, której nikt nie będzie mógł się przeciwstawić. Wybieraj podwładnych z szerokiej puli wyspecjalizowanych jednostek i stwórz armię, która będzie w stanie skutecznie walczyć na zróżnicowanym terenie z dowolnym wrogiem.

Wesnoth posiada wiele historii gotowych do rozegrania. Walcz aby odzyskać tron Wesnoth, którego jesteś prawowitym spadkobiercą... zasmakuj życia młodego oficera, wysłanego by bronić nie-tak-spokojnej granicy... zniszcz hordę nieumarłych przywołanych przez zuchwałego nekromantę, który porwał też twego brata... poprowadź grupę ocalałych elfów w epickiej wyprawie poszukiwania nowego domu.

Ponad 300 jednostek. 20 ras. 6 głównych frakcji. Setki lat historii. Świat Wesnoth jest niezwykle wielki, ograniczony tylko Twoją wyobraźnią - stwórz własne jednostki, zbuduj własne mapy i napisz własne scenariusze, a nawet całe kampanie. Możesz wyzwać nawet do 8 przyjaciół - lub nieznajomych - aby toczyć epickie bitwy w trybie gry wieloosobowej.

== Możliwości ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.9.0-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.9.0-1-175.jpg]
<div class="thumbcaption">Screen z rozgrywki</div></div>
</div>
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.9.0-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.9.0-2-175.jpg]
<div class="thumbcaption">Przykładowa cut scenka</div></div>
</div>

* Stwórz onieśmielającą potęgę, zaczynając od jednego przywódcy i małej ilości złota.
* Ponad 300 typów jednostek w 6 frakcjach, każda z indywidualnymi zdolnościami, bronią i zaklęciami.
* Doświadczone jednostki zdobywają potężne zdolności w miarę awansowania.
* Kilkanaście opcji gry wieloosobowej, z grą przez sieć włącznie.
* Mnóstwo zaprojektowanych map, w tym nieskończona ilość map generowanych losowo.
* Wiele kampanii i zasobów do ściągnięcia poprzez prosty menedżer dodatków wbudowany w gre.
* Funkcja 'Mgła wojny' - prawdziwy test sztuki dowodzenia.
* Zaawansowany język znaczników, który pozwala doświadczonym graczom na tworzenie własnych map, frakcji i scenariuszy.
* Lokalizacja w 54 językach, w tym dostepny język polski.
* Kompatybilna z GNU/Linux, Windows, MacOSX, BeOS, Solaris, FreeBSD, OpenBSD, NetBSD, AmigaOS4, OS/2 & eComStation.

{{Play}}
[[Category:Polish]]

Description/fr

2024-11-13T02:08:17Z

Shiki: adjust numbers

{{Translations}}
== Qu'est-ce que ''Battle for Wesnoth'' ? ==

''Battle for Wesnoth'' est un jeu de stratégie au tour par tour dans un monde médiéval-fantastique.

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-4-175.jpg]
<div class="thumbcaption">L'attaque de foudre magique de Delfador</div></div>
</div>

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-5.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-5-175.jpg]
<div class="thumbcaption">Une embuscade dans la campagne</div></div>
</div>

Construisez une grande armée, transformant progressivement de simples recrues en vétérans aguerris. Dans les parties ultérieures, rappelez vos combattants les plus forts et formez une faction meurtrière contre laquelle il est impossible de lutter ! Choisissez des unités parmi un large éventail de spécialistes, et sélectionnez méticuleusement des troupes avec les atouts adéquats pour combattre efficacement sur différents terrains et contre toute sorte d'opposition.

Wesnoth comporte de nombreuses sagas qui n'attendent que d'être jouées. Luttez pour regagner le trône de Wesnoth, dont vous êtes l'héritier légitime… incarnez un jeune officier envoyé en mission pour garder un avant-poste frontalier pas si paisible… dirigez une quête brutale pour unifier les tribus orcs… surmontez une horde de guerriers morts-vivants contrôlés par un vil nécromancien, qui a par ailleurs pris votre frère en otage… guidez une troupe de survivants elfes dans une quête épique pour trouver une nouvelle terre d'accueil… prenez votre revanche contre les orcs en utilisant l'art sombre de la nécromancie…

Plus de 300 types d'unités. 20 races. 6 factions majeures. Des siècles d'histoire. Le monde de Wesnoth est gigantesque et ses seules limites sont votre créativité : créez vos propres unités personnalisées, réalisez vos propres cartes, et écrivez vos propres scénarios voire des campagnes complètes ! Vous pouvez également défier jusqu'à 8 amis - ou inconnus - et les combattre dans d'épiques batailles en mode multijoueur.

== Caractéristiques ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-2-175.jpg]
<div class="thumbcaption">L'éditeur de carte</div></div>
</div>

* Montez une immense armée de toute pièce, à partir d'un simple chef et d'une petite quantité d'or.
* Plus de 300 types d'unités réparties dans six factions majeures, chacune ayant des capacités, des armes et des sortilèges qui leurs sont propres.
* Les unités expérimentées acquièrent de nouvelles capacités plus puissantes lorsqu'elles évoluent.
* Différents options sont disponibles pour le mode multijoueur, dont les parties sur Internet.
* Un grand nombre de cartes faites sur mesure, et une infinité de cartes aléatoires.
* Des centaines de scénarios de campagne disponibles en téléchargement directement depuis l'interface du jeu.
* Le « brouillard de guerre » peut être activé pour un vrai test de commandement.
* Un langage à balises sophistiqué permet aux utilisateurs avancés de créeer leurs propres cartes, factions et campagnes.
* Un support linguistique très étoffé : 35 langues différentes actuellement disponibles.
* Compatible avec Windows, MacOS X, GNU/Linux, RISC OS, BeOS, Solaris, FreeBSD, OpenBSD, NetBSD, DragonFly BSD, AmigaOS4, OS/2 et eComStation.

{{Play}}

[[Category:French]]

Description/de

2024-11-13T02:07:44Z

Shiki: adjust numbers

{{Translations}}
== Was ist Battle for Wesnoth? ==

''The Battle for Wesnoth'' ist ein rundenbasierendes Strategiespiel mit Fantasy-Thematik.

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-4-175.jpg]
<div class="thumbcaption">Delfador greift mit magischen Blitzen an</div></div>
</div>

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-5.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-5-175.jpg]
<div class="thumbcaption">Ein Hinterhalt in einer Kampagne</div></div>
</div>

Stelle eine mächtige Armee zusammen, indem du aus einfachen Rekruten gestählte Veteranen machst. Später kannst du deine härtesten Krieger wieder einberufen, und niemand wird sich dir mehr in den Weg stellen können! Wähle deine Mitstreiter aus einer Anzahl von spezialisierten Einheitentypen und erstelle eine handverlesene Kriegsmacht, mit deren Stärken du dich auf verschiedenem Gelände gegen jede Art von Widerstand behaupten kannst.

Viele Sagen warten darauf, von dir gespielt zu werden. Kämpfe um den Thron von Wesnoth, dessen legitimer Erbe du bist... schlüpfe in die Rolle eines jungen Offiziers, der ausgesandt wurde, um einen nicht allzu ruhigen Außenposten zu verteidigen... führe einen brutalen Feldzug, um die orkischen Stämme zu vereinigen... besiege eine Gruppe untoter Krieger, die von einem Totenbeschwörer beschworen wurden, der auch deinen Bruder in seiner Gewalt hat... führe eine Gruppe elfischer Überlebender auf ihrer Suche nach einer neuen Heimat... nimm Rache an Orks, indem du die dunklen Künste der Totenbeschwörung praktizierst...

Mehr als 300 Einheitentypen. 20 Rassen. 6 Hauptfraktionen. Hunderte von Geschichtsjahren. Die Welt Wesnoths ist gigantisch und nur von den Grenzen deiner Vorstellungskraft begrenzt — erstelle deine eigenen Einheiten, Karten, Szenarien oder gleich ganze Kampagnen. Du kannst auch bis zu 8 Personen in epischen Mehrspielerschlachten herausfordern.

== Features ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-2-175.jpg]
<div class="thumbcaption">Der Karteneditor</div></div>
</div>

* Erstelle deine Streitmacht, beginnend mit einem einzigen Anführer und einem begrenzten Goldvorrat.
* Mehr als 300 Einheitentypen in 6 Hauptfraktionen, mit diversen Talenten, Waffen und magischen Fähigkeiten.
* Erfahrene Einheiten können sich neue Fähigkeiten aneignen, indem sie sich entwickeln.
* Mehrere Mehrspieleroptionen verfügbar, etwa auch das Spielen über das Internet.
* Jede Menge verschiedene unterschiedlich gestaltete Karten, und eine unbegrenzte Anzahl von Zufallskarten.
* Hunderte von Kampagnenszenarien zum Herunterladen verfügbar über eine einfache spielinterne Prozedur.
* 'Nebel des Krieges' auswählbar, um deine strategichen Fähigkeiten auf die Probe zu stellen.
* Durchdachte Auszeichnungssprache lässt Fortgeschrittene ihre eigenen Fraktionen oder Kapagnen kreieren.
* Große Sprachauswahl – 54 verschiedene Sprachen stehen zur Verfügung.
* Kompatibel mit Windows, Mac OS X, GNU/Linux, RISC OS, BeOS, Solaris, FreeBSD, OpenBSD, NetBSD, DragonFly BSD, AmigaOS4, OS/2 und eComStation.

{{Play}}

Description

2024-11-13T02:06:17Z

Shiki: adjust numbers

{{Translations}}
== What is ''Battle for Wesnoth''? ==

<div class="thumb tleft"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-2-192.jpg]
<div class="thumbcaption">Delfador's magical lightning strike</div></div>
</div>

''The Battle for Wesnoth'' is a turn-based tactical strategy game with a high fantasy theme.

Build up a great army, gradually turning raw recruits into hardened veterans. In later games, recall your toughest warriors and form a deadly host that none can stand against! Choose units from a large pool of specialists, and hand-pick a force with the right strengths to fight well on different terrains against all manner of opposition.

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-12.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-12-192.jpg]
<div class="thumbcaption">Something's in here...</div></div>
</div>

''Wesnoth'' has many different sagas waiting to be played. Fight to regain the throne of Wesnoth, of which you are the legitimate heir... step into the boots of a young officer sent to guard a not-so-sleepy frontier outpost... lead a brutal quest to unite the orcish tribes... vanquish a horde of undead warriors unleashed by a foul necromancer, who also happens to have taken your brother hostage... guide a band of elvish survivors in an epic quest to find a new home... get revenge on the orcs by using the foul art of necromancy...

There are at least three hundred unit types, twenty races, six major factions, and hundreds of years of history. The world of ''Wesnoth'' is absolutely huge and only limited by your creativity — make your own custom units, create your own maps, and write your own scenarios or even full-blown campaigns. You can also challenge up to eight friends — or strangers — and fight in epic ''multiplayer'' fantasy battles.

== Features ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-9.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-9-192.jpg]
<div class="thumbcaption">The map editor</div></div>
</div>

* Build up a formidable fighting force, starting from a single leader and a small amount of gold.
* Over three hundred unit types in six major factions, all with distinctive abilities, weapons and spells.
* Experienced units gain powerful new abilities as they advance.
* Several multiplayer options available, including Internet play.
* Scores of different custom-designed map and unlimited random maps.
* Hundreds of campaign scenarios available for download through a simple in-game dialog.
* ''Fog of War'' feature available for a true test of generalship.
* Sophisticated markup language lets advanced users make their own maps, factions, or campaigns.
* Excellent language support — 54 different languages currently available.
* Compatible with Windows, OS X, and GNU/Linux, as well as BSD distributions such as FreeBSD, OpenBSD, NetBSD, and DragonFly BSD.

{{Play}}

AbilitiesWML

2024-11-12T18:06:46Z

Shiki: /* [damage_type] special */ move version notice outside of the link

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

EditingWesnoth/de

2024-11-08T04:00:41Z

Shiki: /* Windows */ Nur noch 64 bit

{{Translations}}

Alle folgenden Angaben beziehen sich auf Battle for Wesnoth Version 1.16.2.

Auf dieser Seite wird erläutert, wo du die vorhandenen Ressourcen des Hauptspiels findest und wo du neue, benutzerdefinierten Inhalte einfügst. Dies ist die Voraussetzung dafür, eigene neue Inhalte zu erstellen. Benutzerdefinierte Inhalte werden im Wesnoth-Kontext meist mit dem Kürzel '''UMC''' bezeichnet, das für "User Made Content" steht.

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.14.0-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.14.0-1-192.jpg]
<div class="thumbcaption">The main menu</div></div>
</div>

'''Der einfachste Weg, die Spiel- und Benutzerdatenverzeichnisse zu finden, besteht darin, das Spiel zu starten und auf das „i“-Symbol in der unteren linken Ecke des Hauptmenüs zu klicken. Dadurch wird ein Dialogfeld mit vielfältigen Informationen aufgerufen, das u.a. auch die aktuellen Verzeichnispfade des Spiels anzeigt.'''

Von diesem Dialog aus ist es z.B. möglich, einen Verzeichnispfad in die Zwischenablage zu kopieren oder ein Verzeichnis mit dem Dateimanager deines Betriebssystems (unter Windows beispielsweise dem Explorer) zu öffnen.

Betriebssystemspezifische Informationen dazu finden sich in den Abschnitten weiter unten.

== Die Spieldaten-Verzeichnisse ==
'''Die in diesem Abschnitt genannten Verzeichnisse sind NICHT für eigene erstellte Inhalte vorgesehen, sie werden normalerweise NUR von den Spielentwicklern verändert. Die dort abgelegten Daten können aber weitgehend VERWENDET werden.'''

Es spielt keine Rolle, in welchem Verzeichnis das Spiel installiert wurde, es sind immer die Unterverzeichnisse '''data''', '''sounds''' und '''images''' vorhanden. Die anderen vorhandenen Unterverzeichnisse (aktuell: '''fonts''', '''manual''' und '''translations''') sind eher für Entwickler interessant.

Die Verzeichnisse '''sounds''' und '''images''' enthalten Daten, die das Spiel allgemein betreffen. Im '''data'''-Verzeichnis finden sich die spezifischeren Daten des Spiels, unter anderem in folgenden Unterverzeichnissen: '''campaigns''' mit den Hauptkampagnen des Spiels, '''multiplayer''' für die Multiplayer-Karten und '''core''' mit einer Reihe weiterer Unterverzeichnisse, die grundsätzliche Daten des Spiels enthalten (etwa die Einheiten, die Geländetypen, und viele weitere Daten). Die verwendeten Bezeichner sind englisch, sollten aber selbsterklärend sein.

Die Inhalte in den genannten Verzeichnissen geben eine Vorstellung davon, wie die in Wesnoth mitgelieferten Szenarios und Kampagnen aufgebaut sind. Insbesondere im '''core'''-Verzeichnis befinden sich eine Vielzahl von Daten, auf die Ersteller von UMC, also von benutzererstellten Inhalten zurückgreifen können.

Die beiden wichtigsten hier aufgeführten Verzeichnisse, '''data''' und '''core''', werden gelegentlich in abgekürzter Weise bezeichnet (etwa ''game data'', ''core folder'' oder ähnlich). Gemeint sind in aller Regel die oben genannten Verzeichnisse.

=== Wie komme ich dorthin ===
Wie bereits oben herausgestellt, finden sich alle relevanten Verzeichnispfade des Spiels in der Dialogbox, die im Hauptmenü mittels der "'''i'''"-Schaltfläche (in der linken unteren Ecke) aufgerufen wird. Die Bezeichner in der Dialogbox sind selbsterklärend und in aller Regel auch übersetzt, so dass auch unkundige Nutzer klarkommen müssten.

'''Die dort aufgeführten Informationen sind stets aktuell, weil sie direkt aus dem Spiel stammen.''' Im Gegensatz dazu können die Informationen auf ''dieser'' Seite auch schon einmal veraltet sein, etwa wenn sich an der Verzeichnisstruktur eines bestimmten Betriebssystems etwas geändert hat.

==== Windows====
Der Installationpfad ist für Anwendungen (auch für Spiele) frei wählbar, so dass sich die Spielverzeichnisse an nahezu beliebigen Stellen befinden können. Viele Anwender folgen jedoch einer Konvention, nach der sich das Spieldatenverzeichnis '''data''' im folgenden Verzeichnis befindet:
* C:\Programme\Battle for Wesnoth <Version>\data

Der genau Pfad hängt davon ab, auf welcher Partition Windows installiert wurde (dies muss nicht "C:" sein). Der Name des Spielverzeichnisses kann ebenfalls variieren, auch eine <Version> muss nicht angegeben sein.

Um den exakten Installationspfad von Battle for Wesnoth herauszufinden, kann man auch das Desktopsymbol des Spiels rechtsklicken, im Kontextmenü "Eigenschaften" wählen und dann im Eigenschaften-Dialog die Schaltfläche "Dateipfad öffnen" anklicken.

==== macOS ====
Control+click auf das Anwendungssymbol. '''"Show Package Contents"''' auswählen, dann zu '''"Contents"''' →
'''"Resources"''' navigieren.

==== Linux ====

* <b>Custom builds:</b> /usr/local/share/wesnoth
* <b>Debian/Ubuntu packages, or emerge (Gentoo)</b>: /usr/share/games/wesnoth
* <b>Red Hat Linux-based distributions in general (openSUSE, Fedora):</b> /usr/share/wesnoth
* <b>Arch Linux:</b> /usr/share/wesnoth
* <b>Mandriva:</b> /usr/share/games/wesnoth
* <b>Slackware Linux:</b> /usr/local/share/wesnoth

In einer Konsole wird der Installationspfad des Spiels mittels des Befehls <code>wesnoth --path</code> angezeigt.

====BSD====

* <b>OpenBSD package:</b> /usr/local/share/wesnoth

Der Befehl <code>wesnoth --path</code> funktioniert ebenfalls.

== Verzeichnisse mit benutzerdefinierten Inhalten (UMC) ==
'''Die einfachste und sicherste Methode, die Verzeichnisse für benutzerdefinierte Inhalte unabhängig vom Betriebssystem herauszufinden bzw. aufzurufen, ist der im Hauptmenü aufrufbare Info-Dialog.'''

Der genaue Pfad der UMC-Verzeichnisse ist betriebssystemabhängig, die Verzeichnisstruktur innerhalb des Zielverzeichnisses ist jedoch immer gleich. Das Zielverzeichnis (also das Verzeichnis, in dem sich alle Unterverzeichnisse für den UMC befinden) wurde in früheren Versionen des Spiels explizit als "userdata" benannt. <br>
'''Ein Verzeichnis diesen Namens gibt es nicht mehr, die Bezeichnung "userdata" (oder auch "user data") für dieses Verzeichnis wird aber nicht selten immer noch verwendet.'''

Das UMC-Verzeichnis ist das wichtigste Verzeichnis für Ersteller von Inhalten für Wesnoth. Darin findet sich zunächst einmal die sog. preferences-Datei, eine reine Textdatei, die alle gespeicherten Benutzereinstellungen enthält.

Daneben gibt es hier eine Reihe von Unterverzeichnissen, in denen das Spiel die jeweiligen Inhalte erwartet:

* /data/add-ons - Erweiterungen, die entweder selbst erstellt oder mittels des im Spiel integrierten Add-On-Managers installiert wurden. '''Wichtig, da auf dieses Verzeichnis (auch innerhalb der Wiki) häufig Bezug genommen wird!'''
* /editor - Szenarios und Karten, die mittels des im Spiel integrierten Editors erstellt wurden
* /cache - die vom Spiel automatisch erstellten Spiel-Cache-Dateien
* /saves - enthält alle Save-Dateien, also alle abgespeicherten Spielstände

Die preferences-Datei und diese Verzeichnisse werden in [[AddonStructure/de|AddonStructure]] gesondert erläutert.

=== Wie komme ich dorthin ===

==== Windows ====

* <code>Dokumente\My Games\Wesnoth<Version></code>
* vollständiger Pfad: <code>C:\Users\BENUTZERKENNUNG\Dokumente\My Games\Wesnoth<Version></code>
Für BENUTZERKENNUNG ist der Name des aktuell angemeldeten Nutzers (Umgebungsvariable %username%) einzusetzen. Die Version variiert.

==== macOS ====

* Wesnoth 1.14.6 und danach: ~/Library/Containers/org.wesnoth.Wesnoth/Data/Library/Application Support/Wesnoth_<version>
* Ältere Versionen: ~/Library/Application Support/Wesnoth_<version>

'''Anmerkung:''' Das Library-Verzeichnis ist per Voreinstellung versteckt. Zugriff erhält man durch Drücken der Optionen-Taste und die Auswahl von "Go", oder durch die Auswahl von Go > Go to folder und die manuelle Eingabe des Verzeichnis.

==== Linux ====
* ~/.local/share/wesnoth/<Version>
* Mittels flatpak installiert: ~/.var/app/org.wesnoth.Wesnoth/data/wesnoth/<Version>

In einer Konsole zeigt der Befehl <code>wesnoth --config-path</code> das Verzeichnis mit den UMC-Daten.

==== BSD ====
Identisch mit Linux.

== See Also ==

* [[Create]]

[[Category:Create]]

BuildingUnits/fr

2024-11-08T03:53:49Z

Shiki: /* Créer une nouvelle unité */ remove redlink

{{Translations}}

{{Create/fr}}

{| style="float:right; margin-left:1em;"
|__TOC__
|}

En créant du contenu original, vous pourriez vouloir inventer une nouvelle unité. Cette page va vous expliquer toutes les étapes de la création d'une nouvelle unité, et vous montrer comment l'utiliser dans le jeu.

Avant de commencer, vous devez vous souvenir que le tag <b>[[UnitTypeWML | [unit_type]]]</b> créé un nouveau type d'unité, tandis que le tag <b>[[SingleUnitWML | [unit]]]</b> vous permet d'utiliser une unité dans un scénario. Cet article va se focaliser sur le premier tag.

== Créer une nouvelle unité ==

La manière la plus simple de fabriquer une nouvelle unité est de faire une copie du fichier de configuration d'une unité existante, et de modifier cette copie. Toutes les unités présentes dans le jeu de base peuvent être trouvées dans le dossier ''/data/core/units'' à la racine des dossiers du jeu (voir [[EditingWesnoth/fr|cette page]] ou sa [[EditingWesnoth|version anglaise]] pour plus d'instructions pour trouver ces fichiers.

En éditant le fichier, faites bien attention aux différentes propriétés. Si vous oubliez de modifier chaque clef (l'id par exemple), des problèmes pourront apparaître, allant de manque de caractéristiques chez l'unité, jusqu'à un crash du jeu, en passant par une impossibilité de charger l'unité dans le jeu.

Pour des références plus complètes sur les propriétés des unités, vous pouvez visiter [[UnitTypeWML|cette page]]. La plupart de ces références ont une fonction évidente pour des joueurs vétérans, et son courtes et descriptives.

Il y a quelques principes de bases très importants :

* La première attribution d'un type d'unité est sa clef '''id=''', qui est un identifiant unique à chaque type. Pour se référer à un type d'unité dans un scénario, vous devrez utiliser cet id. Il n'est pas traductible. La clef '''name=''' est le nom de l'unité qui est affiché dans l'aide, la table des statut, ou encore dans la barre latérale, qui est traductible. Vous pouvez avoir un id complexe et un nom très simple. Vous devez comprendre que ce n'est pas le même nom que celui renseigné au moment de créer une unité dans un scénario au moyen du tag '''[unit]'''.
* Pour se référencer à un type d'unité, l'id doit être renseigné tel quel, sans faute de frappe et de manière sensible à la casse. Si cela n'est pas respecté, le jeu générera des erreurs '''Unknow Unit'''.
* N'initialisez pas '''movement=''' à 0. Cela crée un comportement bizarre de mouvement infini. Ce bug sera sûrement fixé dans le futur. Pour l'instant, pour rendre une unité immobile, initialisez son tag '''movement''' à 1 et utilisez '''[movement_costs]''' pour la rendre incapable de bouger sur tous les terrains.

== Utiliser votre nouvelle unité ==

Les fichiers de configurations de vos unités doivent être placés dans votre dossier ''units'' de votre add-on, et leurs images dans le dossier ''images/units''. Faites attention, il faut inclure le fichier ''units'' dans votre fichier ''_main.cfg''. L'inclusion pour ce dossier devra être compris à l'intérieur d'un tag '''[units] [/units]'''. Voir [[AddonStructure/fr|cette page]] ([[AddonStructure|en]]) pour un exemple.

All units in this directory will now be accessible in any content loaded under the same <b>#ifdef</b> conditional. You can now allow sides to recruit the unit by listing it in the <b>recruit=</b> key in [side] (see [[SideWML]], place instances of it on the map with their own custom stats via [unit], or anything else you please.

=== Multiplayer factions and eras ===

Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.

<b>Note:</b> Remember that eras and factions is a construct unique to multiplayer.

More detailed instructions on factions and eras can be found in [[BuildingFactions]] and [[EraWML]] articles. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[Team_Color_Shifting]]
* [[Advanced_Animation_Tutorial]]
* [[BuildingScenariosIntermediate]]

BuildingUnits/fr

2024-11-08T03:51:22Z

Shiki: link tags

{{Translations}}

{{Create/fr}}

{| style="float:right; margin-left:1em;"
|__TOC__
|}

En créant du contenu original, vous pourriez vouloir inventer une nouvelle unité. Cette page va vous expliquer toutes les étapes de la création d'une nouvelle unité, et vous montrer comment l'utiliser dans le jeu.

Avant de commencer, vous devez vous souvenir que le tag <b>[[UnitTypeWML | [unit_type]]]</b> créé un nouveau type d'unité, tandis que le tag <b>[[SingleUnitWML | [unit]]]</b> vous permet d'utiliser une unité dans un scénario. Cet article va se focaliser sur le premier tag.

== Créer une nouvelle unité ==

La manière la plus simple de fabriquer une nouvelle unité est de faire une copie du fichier de configuration d'une unité existante, et de modifier cette copie. Toutes les unités présentes dans le jeu de base peuvent être trouvées dans le dossier ''/data/core/units'' à la racine des dossiers du jeu (voir [[EditingWesnoth/fr|cette page]] ou sa [[EditingWesnoth|version anglaise]] pour plus d'instructions pour trouver ces fichiers.

En éditant le fichier, faites bien attention aux différentes propriétés. Si vous oubliez de modifier chaque clef (l'id par exemple), des problèmes pourront apparaître, allant de manque de caractéristiques chez l'unité, jusqu'à un crash du jeu, en passant par une impossibilité de charger l'unité dans le jeu.

Pour des références plus complètes sur les propriétés des unités, vous pouvez visiter [[UnitTypeWML/fr|cette page]] ([[UnitTypeWML|en]]). La plupart de ces références ont une fonction évidente pour des joueurs vétérans, et son courtes et descriptives.

Il y a quelques principes de bases très importants :

* La première attribution d'un type d'unité est sa clef '''id=''', qui est un identifiant unique à chaque type. Pour se référer à un type d'unité dans un scénario, vous devrez utiliser cet id. Il n'est pas traductible. La clef '''name=''' est le nom de l'unité qui est affiché dans l'aide, la table des statut, ou encore dans la barre latérale, qui est traductible. Vous pouvez avoir un id complexe et un nom très simple. Vous devez comprendre que ce n'est pas le même nom que celui renseigné au moment de créer une unité dans un scénario au moyen du tag '''[unit]'''.
* Pour se référencer à un type d'unité, l'id doit être renseigné tel quel, sans faute de frappe et de manière sensible à la casse. Si cela n'est pas respecté, le jeu générera des erreurs '''Unknow Unit'''.
* N'initialisez pas '''movement=''' à 0. Cela crée un comportement bizarre de mouvement infini. Ce bug sera sûrement fixé dans le futur. Pour l'instant, pour rendre une unité immobile, initialisez son tag '''movement''' à 1 et utilisez '''[movement_costs]''' pour la rendre incapable de bouger sur tous les terrains.

== Utiliser votre nouvelle unité ==

Les fichiers de configurations de vos unités doivent être placés dans votre dossier ''units'' de votre add-on, et leurs images dans le dossier ''images/units''. Faites attention, il faut inclure le fichier ''units'' dans votre fichier ''_main.cfg''. L'inclusion pour ce dossier devra être compris à l'intérieur d'un tag '''[units] [/units]'''. Voir [[AddonStructure/fr|cette page]] ([[AddonStructure|en]]) pour un exemple.

All units in this directory will now be accessible in any content loaded under the same <b>#ifdef</b> conditional. You can now allow sides to recruit the unit by listing it in the <b>recruit=</b> key in [side] (see [[SideWML]], place instances of it on the map with their own custom stats via [unit], or anything else you please.

=== Multiplayer factions and eras ===

Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.

<b>Note:</b> Remember that eras and factions is a construct unique to multiplayer.

More detailed instructions on factions and eras can be found in [[BuildingFactions]] and [[EraWML]] articles. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[Team_Color_Shifting]]
* [[Advanced_Animation_Tutorial]]
* [[BuildingScenariosIntermediate]]

BuildingUnits/fr

2024-11-08T03:49:24Z

Shiki: /* Utiliser votre nouvelle unité */

{{Translations}}

{{Create/fr}}

{| style="float:right; margin-left:1em;"
|__TOC__
|}

En créant du contenu original, vous pourriez vouloir inventer une nouvelle unité. Cette page va vous expliquer toutes les étapes de la création d'une nouvelle unité, et vous montrer comment l'utiliser dans le jeu.

Avant de commencer, vous devez vous souvenir que le tag '''[[UnitTypeWML/fr|[unit_type]]]''' ([[UnitTypeWML|en]]) créé un nouveau type d'unité, tandis que le tag '''[[SingleUnitWML/fr|[unit]]]''' ([[SingleUnitWML|en]]) vous permet d'utiliser une unité dans un scénario. Cet article va se focaliser sur le premier tag.

== Créer une nouvelle unité ==

La manière la plus simple de fabriquer une nouvelle unité est de faire une copie du fichier de configuration d'une unité existante, et de modifier cette copie. Toutes les unités présentes dans le jeu de base peuvent être trouvées dans le dossier ''/data/core/units'' à la racine des dossiers du jeu (voir [[EditingWesnoth/fr|cette page]] ou sa [[EditingWesnoth|version anglaise]] pour plus d'instructions pour trouver ces fichiers.

En éditant le fichier, faites bien attention aux différentes propriétés. Si vous oubliez de modifier chaque clef (l'id par exemple), des problèmes pourront apparaître, allant de manque de caractéristiques chez l'unité, jusqu'à un crash du jeu, en passant par une impossibilité de charger l'unité dans le jeu.

Pour des références plus complètes sur les propriétés des unités, vous pouvez visiter [[UnitTypeWML/fr|cette page]] ([[UnitTypeWML|en]]). La plupart de ces références ont une fonction évidente pour des joueurs vétérans, et son courtes et descriptives.

Il y a quelques principes de bases très importants :

* La première attribution d'un type d'unité est sa clef '''id=''', qui est un identifiant unique à chaque type. Pour se référer à un type d'unité dans un scénario, vous devrez utiliser cet id. Il n'est pas traductible. La clef '''name=''' est le nom de l'unité qui est affiché dans l'aide, la table des statut, ou encore dans la barre latérale, qui est traductible. Vous pouvez avoir un id complexe et un nom très simple. Vous devez comprendre que ce n'est pas le même nom que celui renseigné au moment de créer une unité dans un scénario au moyen du tag '''[unit]'''.
* Pour se référencer à un type d'unité, l'id doit être renseigné tel quel, sans faute de frappe et de manière sensible à la casse. Si cela n'est pas respecté, le jeu générera des erreurs '''Unknow Unit'''.
* N'initialisez pas '''movement=''' à 0. Cela crée un comportement bizarre de mouvement infini. Ce bug sera sûrement fixé dans le futur. Pour l'instant, pour rendre une unité immobile, initialisez son tag '''movement''' à 1 et utilisez '''[movement_costs]''' pour la rendre incapable de bouger sur tous les terrains.

== Utiliser votre nouvelle unité ==

Les fichiers de configurations de vos unités doivent être placés dans votre dossier ''units'' de votre add-on, et leurs images dans le dossier ''images/units''. Faites attention, il faut inclure le fichier ''units'' dans votre fichier ''_main.cfg''. L'inclusion pour ce dossier devra être compris à l'intérieur d'un tag '''[units] [/units]'''. Voir [[AddonStructure/fr|cette page]] ([[AddonStructure|en]]) pour un exemple.

All units in this directory will now be accessible in any content loaded under the same <b>#ifdef</b> conditional. You can now allow sides to recruit the unit by listing it in the <b>recruit=</b> key in [side] (see [[SideWML]], place instances of it on the map with their own custom stats via [unit], or anything else you please.

=== Multiplayer factions and eras ===

Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.

<b>Note:</b> Remember that eras and factions is a construct unique to multiplayer.

More detailed instructions on factions and eras can be found in [[BuildingFactions]] and [[EraWML]] articles. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[Team_Color_Shifting]]
* [[Advanced_Animation_Tutorial]]
* [[BuildingScenariosIntermediate]]

BuildingUnits/de

2024-11-08T03:49:03Z

Shiki: /* Die eigene Einheit benutzen */

{{Translations}}
{{Create/de}}

{| style="float:right; margin-left:1em;"
|__TOC__
|}

Wenn man eigene Inhalte erstellt, liegt es nahe dabei mindestens eine coole neue Einheit zu erstellen. Dieser Leitfaden wird dich dabei unterstützen, eine neue Einheit zu erstellen und dir erörtern, wie man diese im Spiel benutzen kann.

Bevor du anfängst, solltest du dir ins Gedächtnis rufen, dass der <b>[[UnitTypeWML | [unit_type]]]</b> tag eine neu Art Einheit erstellt. Der <b>[[SingleUnitWML | [unit]]]</b> tag erlaubt es dir, diese Einheit im Szenario zu verwenden, was im Folgenden näher erläutert wird.

== Eine eigene Einheit erstellen ==

Der einfachste Weg, um eine neue Einheit zu erstellen, wäre die Konfigurationsdatei einer existierenden zu duplizieren und danach zu modifizieren. Alle Einheiten des Spiels können im <i>data/core/units</i> Verzeichnis gefunden werden. (siehe [[EditingWesnoth]])

Bei der Editierung der Datei, solltest du auf die Eigenschaftsschlüssel achtgeben. Wenn du vergisst, jeden Schlüssel zu modifizieren, (beispielsweise der einzigartige id-Schlüssel) werden höchst wahrscheinlich einige Probleme auftreten, die verschieden schwerwiegend sein können. Die würden dann von der Nichtpräsenz von Eigenschaften der Einheit bis dazu reichen, dass das Spiel die Datei nicht laden wird. Im schlimmsten Fall sogar zu einem Spielabsturz...

Einen kompletten Überblick zu Eigenschaften von Einheiten findest du bei [[UnitTypeWML]]. Die meisten sind aber selbsterklärend für Leute, die Wesnoth schon lange gespielt haben. Die tags sind zwar kurz, aber beschreiben das, was sie machen schon ganz gut.

Es gibt einige wichtige Grundlagen:

* Die erste Eigenschaft einer Einheitenart ist der <b>id=</b> Schlüssel, der für jede einzigartig ist. Benutze die id immer, wenn du auf die Einheitenart in einem Szenario verweist. Die id ist nicht übertragbar. Der <b>name=</b> Schlüssel ist der angezeigte Name der Einheitenart, der im Hilfsmenü, der Statustabelle und auf der Seitenleiste zu sehen ist, er kann hingegen übertragen werden. Du kannst somit eine komplexe id, aber einen einfachen Namen vergeben. Beachte, dass dieser <b>NICHT</b> der selbe Name wie der einer spezifischen Instanz einer Einheit, die durch [unit] erstellt wurde, sein darf.
* Beim Verweis auf die neue Truppenart, muss die id wörtlich ohne Tippfehler mit Groß- und Kleinschreibung wiedergegeben werden. Wenn du das nicht beachtest, wird dich das Spiel höchstwahrscheinlich mit ,,Unbekannte Einheit"-Fehlern überschwemmen.
* Setze <b>movement=</b> niemals 0. Es würde in ein komisches, unendliches Bewegungsverhalten resultieren, was vielleicht in der Zukunft behoben wird. Also setze fürs Erste, um eine bewegungslose Einheit zu haben, ,,movement" auf 1 und benutze [movement_costs], damit die Einheit auf keinem Gelände fähig ist, sich zu bewegen.

== Die eigene Einheit benutzen ==

Die Konfigurationsdateien von eigenen Einheiten sollten in dem <i>,,units"</i> -Verzeichnis deines add-ons platziert werden. Deren eigene Grafiken gehören dann in das <i>images/units</i> Verzeichnis. Das <i>units</i> Verzeichnis musst du übrigens in deiner _main.cfg erwähnen. Die Einbeziehung dieses Verzeichnis sollte aber in einem <b>[units][/units]</b> tag Paar erfolgen. Für Beispiele siehe [[AddonStructure]].

Sämtliche Einheiten in diesem Verzeichnis werden nun in jeglicher Datei erreichbar sein, die durch die selbe <b>#ifdef</b> Bedingung geladen wurde.
Du kannst nun Fraktionen erlauben, die Einheit zu rekrutieren, indem du diese in den <b>recruit=</b> Schlüssel von [side] aufnimmst (siehe [[SideWML]]), platziere Instanzen davon auf der Karte mit ihren eigenen Werten über [unit] oder anderen Methoden.

=== Mehrspieler Fraktionen und Ären ===

Ein weitere verbreitete Nutzung von eigenen Einheiten ist es, diese in einer Mehrspielerfraktion zu gruppieren und eine oder mehrere Fraktionen in einer Ära einzubinden. Eine Fraktion besteht aus mehreren Einheiten, die ein bestimmtes Leitmotiv verbindet. Beispielsweise die Loyalisten. Eine Ära hingegen besteht aus verschiedenen Fraktionen, die ein Leitmotiv oder ähnliches verbindet; Ein Beispiel wäre das Standardzeitalter, welches alle Zeitalter enthält, die im Mehrspieler benutzt werden.

<b>Notiz:</b> Ären/Zeitalter und Fraktionen beschränken sich nur auf den Mehrspieler.

Eine weitaus detaillierterer Leitfaden zu Fraktionen und Ären kann im [[EraWML]] Artikel gefunden werden. Eine Fraktion muss immer von einem Zeitalter beinhaltet werden. Des weiteren kannst du keine Einheiten einem Zeitalter des Hauptspiels hinzufügen.

== Weiteres ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[Team_Color_Shifting]]
* [[Advanced_Animation_Tutorial]]
* [[BuildingScenariosIntermediate]]
* [[BuildingFactions]]

BuildingUnits

2024-11-08T03:48:23Z

Shiki: /* Using your new unit */

{{Translations}}

{{Create}}

{| style="float:right; margin-left:1em;"
|__TOC__
|}

When creating custom content, you might want to create a cool new unit. This page will walk you through the creation of a new unit and discuss how you can use it in-game.

Before you begin, you should be remember that the <b>[[UnitTypeWML | [unit_type]]]</b> tag will create a new type of unit, while the <b>[[SingleUnitWML | [unit]]]</b> tag allows you to use the unit in your scenario. This article will focus on the use of the former.

== Creating a new unit ==

The easiest way to make a new unit is to make a copy of an existing unit's configuration file and modify it. All units shipped with the game can be found in the game's <i>data/core/units</i> directory (see [[EditingWesnoth]] for how to find it).

When you are editing the file, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game.

For complete reference on unit properties see [[UnitTypeWML]]. Most of them are self-explanatory to anyone who has played Wesnoth for very long, and are brief but descriptive.

There are a few important basics:

* The first attribute of a unit type is the <b>id=</b> key, which is a unique identifier for that type. Whenever referring to a unit type via in a scenario, you use this id. It is not translatable. The <b>name=</b> key is the displayed name of the unit type in places such as help, the status table, and the sidebar, and is translatable. You can have a complex id, but a simple name. Remember that this is <b>NOT</b> the same as the name of a specific instance of a unit created in a scenario via [unit].
* When referencing the unit type, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the game will throw Unknown Unit errors.
* Do not set <b>movement=</b> to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.

== Using your new unit ==

Custom unit configuration files should be put in your add-on's <i>units</i> directory, and their custom graphics in the <i>images/units</i> directory. Be sure to have the <i>units</i> directory included from your _main.cfg. The include for this directory, however, should be wrapped in a <b>[units][/units]</b> tag pair. See [[AddonStructure]] for an example.

All units in this directory will now be accessible in any content loaded under the same <b>#ifdef</b> conditional. You can now allow sides to recruit the unit by listing it in the <b>recruit=</b> key in [side] (see [[SideWML]], place instances of it on the map with their own custom stats via [unit], or anything else you please.

=== Multiplayer factions and eras ===

Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.

<b>Note:</b> Remember that eras and factions is a construct unique to multiplayer.

More detailed instructions on factions and eras can be found in the [[EraWML]] article. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[Team_Color_Shifting]]
* [[Advanced_Animation_Tutorial]]
* [[BuildingScenariosIntermediate]]
* [[BuildingFactions]]

BuildingMaps/es

2024-11-08T03:46:26Z

Shiki: /* Formato de datos del mapa */ remove outdated part

{{Translations}}
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">
<br>

Un mapa, es sólo un conjunto de cuerdas de terreno dispuestas en un rectángulo (lo que se conoce como "mapa de datos"). Hay dos maneras de utilizar este rectángulo en un archivo: como un mapa independiente o dentro de un escenario. La manera más fácil de crear mapas es utilizar el "Editor de Mapas", pero si desea comprender mejor cómo funcionan los mapas le recomendamos leer un poco sobre el formato de datos del mapa.

Esta página explica ese formato, y luego tiene algunos consejos sobre el editor, guardar archivos, y cómo jugar en un mapa una vez que usted lo ha hecho. Para obtener instrucciones sobre la forma de distribuir los mapas, consulte [[Distributing_content]].

== Creando un mapa ==

Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward. Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]. If you run into trouble with the map editor, go ahead and ask for help on the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum].

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

=== Formato de datos del mapa ===

This is not the Matrix. You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:

* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== ¿Ahora qué? ==

You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.

=== Jugar en su propio mapa ===

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear '''at the top''' of the map choices screen.

When creating a game on the multiplayer server, your map will be described to other players as a "User Map" and any replays stored on the server will refer to the game as "User Map."

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

=== Colabore compartiendo su mapa ===

Cuando esté listo para compartir su mapa con el mundo, coloquelo en el [http://www.wesnoth.org/forum/viewforum.php?f=15 foro de desarrollo multijugador] or package it to be distributed on the in-game add-ons server.

== Nota ==

There is a proposed update for the map format coming up soon. Please read this to find out more.

[http://forums.wesnoth.org/viewtopic.php?f=10&t=36323 New map format]

== También vea ==

* [[TerrainCodesWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]
<br><br>
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">

[[Category:Create]]

BuildingMaps/es

2024-11-08T03:44:52Z

Shiki:

{{Translations}}
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">
<br>

Un mapa, es sólo un conjunto de cuerdas de terreno dispuestas en un rectángulo (lo que se conoce como "mapa de datos"). Hay dos maneras de utilizar este rectángulo en un archivo: como un mapa independiente o dentro de un escenario. La manera más fácil de crear mapas es utilizar el "Editor de Mapas", pero si desea comprender mejor cómo funcionan los mapas le recomendamos leer un poco sobre el formato de datos del mapa.

Esta página explica ese formato, y luego tiene algunos consejos sobre el editor, guardar archivos, y cómo jugar en un mapa una vez que usted lo ha hecho. Para obtener instrucciones sobre la forma de distribuir los mapas, consulte [[Distributing_content]].

== Creando un mapa ==

Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward. Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]. If you run into trouble with the map editor, go ahead and ask for help on the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum].

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

=== Formato de datos del mapa ===

This is not the Matrix. You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== ¿Ahora qué? ==

You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.

=== Jugar en su propio mapa ===

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear '''at the top''' of the map choices screen.

When creating a game on the multiplayer server, your map will be described to other players as a "User Map" and any replays stored on the server will refer to the game as "User Map."

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

=== Colabore compartiendo su mapa ===

Cuando esté listo para compartir su mapa con el mundo, coloquelo en el [http://www.wesnoth.org/forum/viewforum.php?f=15 foro de desarrollo multijugador] or package it to be distributed on the in-game add-ons server.

== Nota ==

There is a proposed update for the map format coming up soon. Please read this to find out more.

[http://forums.wesnoth.org/viewtopic.php?f=10&t=36323 New map format]

== También vea ==

* [[TerrainCodesWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]
<br><br>
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">

[[Category:Create]]

BuildingMaps/es

2024-11-08T03:41:23Z

Shiki: Add translation list

{{Translations}}
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">
<br>

Un mapa, es sólo un conjunto de cuerdas de terreno dispuestas en un rectángulo (lo que se conoce como "mapa de datos"). Hay dos maneras de utilizar este rectángulo en un archivo: como un mapa independiente o dentro de un escenario. La manera más fácil de crear mapas es utilizar el "Editor de Mapas", pero si desea comprender mejor cómo funcionan los mapas le recomendamos leer un poco sobre el formato de datos del mapa.

Esta página explica ese formato, y luego tiene algunos consejos sobre el editor, guardar archivos, y cómo jugar en un mapa una vez que usted lo ha hecho. Para obtener instrucciones sobre la forma de distribuir los mapas, consulte Distributing_content

The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it. For instructions on how to distribute maps, see [[Distributing_content]].

== Creando un mapa ==

Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward. Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]. If you run into trouble with the map editor, go ahead and ask for help on the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum].

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

=== Formato de datos del mapa ===

This is not the Matrix. You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== ¿Ahora qué? ==

You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.

=== Jugar en su propio mapa ===

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear '''at the top''' of the map choices screen.

When creating a game on the multiplayer server, your map will be described to other players as a "User Map" and any replays stored on the server will refer to the game as "User Map."

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

=== Colabore compartiendo su mapa ===

Cuando esté listo para compartir su mapa con el mundo, coloquelo en el [http://www.wesnoth.org/forum/viewforum.php?f=15 foro de desarrollo multijugador] or package it to be distributed on the in-game add-ons server.

== Nota ==

There is a proposed update for the map format coming up soon. Please read this to find out more.

[http://forums.wesnoth.org/viewtopic.php?f=10&t=36323 New map format]

== También vea ==

* [[TerrainCodesWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]
<br><br>
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">

[[Category:Create]]

BuildingMaps/es

2024-11-08T03:39:16Z

Shiki: fix formatting

<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">
<br>

Un mapa, es sólo un conjunto de cuerdas de terreno dispuestas en un rectángulo (lo que se conoce como "mapa de datos"). Hay dos maneras de utilizar este rectángulo en un archivo: como un mapa independiente o dentro de un escenario. La manera más fácil de crear mapas es utilizar el "Editor de Mapas", pero si desea comprender mejor cómo funcionan los mapas le recomendamos leer un poco sobre el formato de datos del mapa.

Esta página explica ese formato, y luego tiene algunos consejos sobre el editor, guardar archivos, y cómo jugar en un mapa una vez que usted lo ha hecho. Para obtener instrucciones sobre la forma de distribuir los mapas, consulte Distributing_content

The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it. For instructions on how to distribute maps, see [[Distributing_content]].

== Creando un mapa ==

Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward. Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]. If you run into trouble with the map editor, go ahead and ask for help on the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum].

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

=== Formato de datos del mapa ===

This is not the Matrix. You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== ¿Ahora qué? ==

You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.

=== Jugar en su propio mapa ===

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear '''at the top''' of the map choices screen.

When creating a game on the multiplayer server, your map will be described to other players as a "User Map" and any replays stored on the server will refer to the game as "User Map."

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

=== Colabore compartiendo su mapa ===

Cuando esté listo para compartir su mapa con el mundo, coloquelo en el [http://www.wesnoth.org/forum/viewforum.php?f=15 foro de desarrollo multijugador] or package it to be distributed on the in-game add-ons server.

== Nota ==

There is a proposed update for the map format coming up soon. Please read this to find out more.

[http://forums.wesnoth.org/viewtopic.php?f=10&t=36323 New map format]

== También vea ==

* [[TerrainCodesWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]
<br><br>
<div class="navtemplate">Enlaces de creación: [[BuildingMaps/es | Mapas]] | [[BuildingScenarios/es | Escenarios]] | [[BuildingCampaigns/es | Campañas]] | [[MultiplayerContent| Multijugadores]] | [[BuildingUnits | Unidades]] </div class="navtemplate">

[[Category:Create]]

Description/ukr

2024-11-08T03:27:42Z

Shiki: Add translation list

{{Translations}}
== Що таке ''Battle for Wesnoth''? ==

<div class="thumb tleft"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-2-192.jpg]
<div class="thumbcaption">Магічний удар блискавкою Делфадора</div></div>
</div>

''The Battle for Wesnoth'' - це покрокова тактична стратегія у світі епічного фентезі.

Зберіть величну армію, поступово перетворюючи сирих новобранців на загартованих ветеранів. У наступних іграх покличте своїх найсильніших воїнів і сформуйте смертоносну армію, проти якої ніхто не зможе встояти! Обирайте одиниці з великого кола фахівців і власноруч підбирайте сили з потрібними силами, щоб добре битися на різних місцевостях проти різного роду супротивників.

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-12.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.12.0-12-192.jpg]
<div class="thumbcaption">Тут щось є...</div></div>
</div>

''Wesnoth'' has many different sagas waiting to be played. Fight to regain the throne of Wesnoth, of which you are the legitimate heir... step into the boots of a young officer sent to guard a not-so-sleepy frontier outpost... lead a brutal quest to unite the orcish tribes... vanquish a horde of undead warriors unleashed by a foul necromancer, who also happens to have taken your brother hostage... guide a band of elvish survivors in an epic quest to find a new home... get revenge on the orcs by using the foul art of necromancy...

''Wesnoth'' має багато різних саг, які чекають на те, щоб в них зіграли. Бийтесь, аби повернути трон ''Wesnoth''а, законним спадкоємцем якого ви є... спробуйте себе у ролі молодого офіцера, якого послано охороняти ''не такий вже й сонний'' прикордонний пост... очольте жорстокий квест, аби об’єднати племена орків... знищіть орду воїнів-нежити, випущених нечестивим некромантом, який також взяв у заручники вашого брата... поведіть групу ельфійських біженців у епічну пригоду, щоб знайти новий дім... помстіться оркам, скориставшись нечестивим мистецтвом некромантії...

У ''Wesnoth'' існує щонайменше двісті типів підрозділів, шістнадцять рас, шість основних фракцій і сотні років історії. Світ ''Wesnoth'' абсолютно величезний і обмежений лише вашою творчістю -- створюйте власні юніти, створюйте власні мапи та пишіть власні сценарії, або навіть повномасштабні кампанії. Ви також можете кинути виклик до восьми друзям (або незнайомцям), і битися в епічних ''багатокористувацьких'' фантастичних битвах.

Play/es

2024-11-08T03:25:34Z

Shiki: /* El mundo de Wesnoth */ new link

{{Translations}}
== Obtener La Batalla por Wesnoth ==
* [[Description/es | Sobre el proyecto]]
* [[Download/es | Descargas y código fuente]]
* [[CompilingWesnoth/es | Compilación de Wesnoth]]
* [[WesnothBinariesLinux/es | Instalación de binarios en Linux -- la manera más sencilla]]

== Jugando a La Batalla por Wesnoth ==
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-4-175.jpg]
<div class="thumbcaption">Los elfos asediados</div></div>
</div>

* [[GettingStarted/es | Comenzando]]
* [[WesnothManual/es | Manual del juego]]
* [[Mainline_Campaigns/es | Campañas oficiales]]
* [[Competitive_Gaming/es | Competiciones]]
* [[MP_CodeOfConduct/es | Sobre el modo multijugador]]
* [[Guide_to_UMC_Campaigns | Contenido elaborado por los usuarios - Campañas]]
* [[FAQ | Preguntas frecuentes]]

== Jugadores avanzados ==
* [[CommandMode | Referencia de comandos de multijugador y depuración]]
* [[AdvancedTactics | Tácticas avanzadas]]
* [http://units.wesnoth.org/ Referencia de unidades]
* [[MultiplayerServers | Servidores multijugador]]
* [[How to play... | Fascículos de "Cómo jugar con"]]

== El mundo de Wesnoth ==
<div class="thumb tright"><div>
[https://www.wesnoth.org/wiki-images/wesnoth-map-1.12.jpg https://www.wesnoth.org/wiki-images/wesnoth-map-1.12-175.jpg]
<div class="thumbcaption">Wesnoth y territorios aledaños</div></div>
</div>

* [[Timeline of Wesnoth | Historia de Wesnoth]]
* [[Geography of Wesnoth | Geografía de Wesnoth]]
* [[WesnothFigures | Personajes notables de Wesnoth]]
* [[Races | Razas y criaturas en Wesnoth]]
* [[Poetry of Wesnoth | Cancionero de Wesnoth]]

== Miscelánea ==
* [[WhatArePlayersSaying | Comentarios de los jugadores]]
* [[WesnothReviews | Críticas (por terceras partes)]]
* [[Screenshots | Capturas de pantalla]]
* [[FAQ#Do_you_want_help_making_this_game.3F_How_can_I_help.3F | Ayuda a mejorar el juego]]
* [[Glossary | Glosario de Wesnoth]]
* [[RelatedTools | Herramientas relacionadas]]
__NOTOC__

[[Category:Playing Wesnoth]]

Play/zh-Hans

2024-11-08T03:25:05Z

Shiki: /* 韦诺的世界 */ new link

{{Translations}}
== 获取韦诺之战 ==
* [[Description/zh-Hans|关于本项目]]
* [[Download/zh-Hans|下载与源代码页]]
* [[CompilingWesnoth|编译韦诺]]
* [[WesnothBinariesLinux|Linux二进制包安装——简便的方法]]

== 享受韦诺之战 ==
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-4-175.jpg]
<div class="thumbcaption">被围困的精灵</div></div>
</div>

* [[GettingStarted|开始吧]]
* [[WesnothManual|游戏手册]]
* [[Mainline_Campaigns|官方战役]]
* [[Competitive_Gaming |游戏竞技]]
* [[MP_CodeOfConduct |多人游戏信息]]
* [[Guide_to_UMC_Campaigns |用户自制内容(UMC)战役]]

* [[FAQ|常见问题]]

== 高级玩家 ==
* [[CommandMode|调试和多人游戏命令参考]]
* [[AdvancedTactics|先进战术]]
* [http://units.wesnoth.org/ 单位参考]
* [[MultiplayerServers|多人游戏服务器]]
* [[How to play...|“怎么玩”系列文章]]

== 韦诺的世界 ==
<div class="thumb tright"><div>
[https://www.wesnoth.org/wiki-images/wesnoth-map-1.12.jpg https://www.wesnoth.org/wiki-images/wesnoth-map-1.12-175.jpg]
<div class="thumbcaption">韦诺和周围的陆地</div></div>
</div>

* [[Timeline of Wesnoth|韦诺时间线]]
* [[Geography of Wesnoth/zh-Hans|韦诺地理学]]
* [[WesnothFigures|韦诺著名人物]]
* [[Races|韦诺的生物种族]]
* [[Poetry of Wesnoth|韦诺的诗歌]]

== 杂项 ==
* [[WhatArePlayersSaying|韦诺玩家的评论]]
* [[WesnothReviews|第三方韦诺评价]]
* [[Screenshots|截图]]
* [[FAQ#Do_you_want_help_making_this_game.3F_How_can_I_help.3F|如何改善游戏]]
* 一份韦诺[[Glossary|术语表]]
* [[RelatedTools|相关工具]]
__NOTOC__

[[Category:Playing Wesnoth]]

Play/pl

2024-11-08T03:24:26Z

Shiki: /* Świat Wesnoth */ mapa link

{{Translations}}

Ostatnia edycja: 16 stycznia 2014

== Zdobywanie Bitwy o Wesnoth==
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.7-3.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.7-3-175.jpg]
<div class="thumbcaption">Wybór mapy</div></div>
</div>
* [[PL:Description|O projekcie]]
* [[Download|Pobieranie (''en'')]]
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Kompilowanie Wesnoth (''en'')]
* [[WesnothBinariesLinux| Linux prosty spsób instalacji (''en'')]]

== Granie w Bitwę o Wesnoth ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.8-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.8-1-175.jpg]
<div class="thumbcaption">Screen z rozgrywki</div></div>
</div>

* [[GettingStarted|Początki (''en'')]]
*[http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/1.10/doc/manual/manual.pl.html Podręcznik użytkownika]
* [[BasicStrategy|Podstawy strategii (''en'')]]
* [[MainlineCampaigns|Scenariusze podstawowe (''en'')]]
* [[MP_CodeOfConduct | Informacje o grze multiplayer (''en'')]]
* [[Guide_to_UMC_Content |Zawartość dodatkowa stworzona przez fanów (''en'')]]
* [[FAQ|FAQ (''en'')]]

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.7-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.7-2-175.jpg]
<div class="thumbcaption">Menadżer dodatków</div></div>
</div>

== Zaawansowani Gracze ==
* [[CommandMode|Tryb poleceń (''en'')]]
* [[AdvancedTactics|Zaawansowana taktyka (''en'')]]
* [http://units.wesnoth.org Jednostki (''en'')]
* [[Competitive_Gaming | Zorganizowane gry multipalyer (''en'')]]
* [[MultiplayerServers|Serwery multiplayer (''en'')]]
* [[How to play...|Jak grać... (''en'')]]

== Świat Wesnoth ==
<div class="thumb tright"><div>
[https://www.wesnoth.org/wiki-images/wesnoth-map-1.12.jpg https://www.wesnoth.org/wiki-images/wesnoth-map-1.12-175.jpg]
<div class="thumbcaption">Mapa Wesnoth</div></div>
</div>

* [[Timeline of Wesnoth|Historia (''en'')]]
* [[Geography of Wesnoth|Geografia (''en'')]]
* [[WesnothFigures|Wybitne postacie (''en'')]]
* [[Races|Rasy (''en'')]]

== Rozmaitości ==
* [[WhatArePlayersSaying|Komentarze graczy (''en'')]]
* [[WesnothReviews|Recenzje (''en'')]]
* [[Screenshots|Screeny]]
* [[FAQ#Do_you_want_help_making_this_game.3F_How_can_I_help.3F|Jak pomóc rozwijać grę (''en'')]]
* [[Glossary|Słowniczek (''en'')]]
* [[RelatedTools|Narzędzia (''en'')]]
__NOTOC__

[[Category:Playing Wesnoth]]
[[Category:Polish]]

Create/pl

2024-11-08T03:20:12Z

Shiki: /* Świat Wesnoth */ change image link

{{Translations}}
{| style="float:right"
|
__TOC__
|}

Jesteś zainteresowany tworzeniem własnych scenariusz i kampanii? Jedną z głównych zalet gry Battle for Wesnoth jest jej otwartość. Gracze mogą z łatwością tworzyć nowe mapy, jednostki, rasy, scenariusze, grafikę, muzykę, całe kampanie i wiele wiele więcej. Dostęp do plików gry jest na swój sposób tak prosty, jak i trudny; jeśli masz choćby prosty edytor tekstowy, posiadasz narzędzie pozwalające na wszelkie zmiany. Jednakże nauka WML (''ang.'' Wesnoth Markup Language) wymaga pewnego wysiłku. Ta sekcja przeprowadzi Cię przez proces tworzenia i rozprowadzania własnych dodatków.

== Wstęp ==
Zanim cokolwiek zmodyfikujesz albo dodasz, istotne jest, abyś rozumiał w jaki sposób gra przechowuje dane. Ten artykuł tłumaczy strukturę folderów gry, oraz wprowadza pojęcie folderu ''userdata''.
* [[EditingWesnoth|Edycja The Battle for Wesnoth (''en'')]]
Nie jest on nadmiernie przesiąknięty informacjami, lecz zaznajomienie się z nim jest praktycznie konieczne do możliwości pracy nad własnymi dodatkami.

== Co i jak mogę tworzyć? ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.8-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.8-4-175.jpg]
<div class="thumbcaption">Edytor map</div></div>
</div>

Możliwości tworzenia nowych dodatków do Battle for Wesnoth są ograniczone tylko wyobraźnią ich autora. Poniższa lista oferuje szybki dostęp do stron ze szczegółowymi informacjami na temat edycji i tworzenia różnych elementów gry.

* [[BuildingMaps|Mapy (''en'')]] - określają układ pól terenu
* [[BuildingScenarios|Scenariusze (''en'')]] - dodają wydarzenia na mapie, robiąc ją bardziej grywalną
* [[BuildingCampaigns|Kampanie (''en'')]] - jak połączyć wszystko w kampanię
* [[MultiplayerContent|Kampanie multiplayer (''en'')]] - tworzenie kampanii dla wielu graczy '''(przestarzałe)'''
* [[BuildingUnits|Jednostki (''en'')]]
* [[BuildingFactions|Frakcje i ery multiplayer (''en'')]]
* [[Create Art|Grafika (''en'')]]
* [[Create Music|Muzyka (''en'')]]
* [[Create Writing|Teksty (''en'')]]
* [[WesnothTranslations|Tłumaczenia (''en'')]] - prace nad tłumaczeniem Wesnoth
* [[Practical Guide to Modifying AI Behavior|Sztuczną inteligencje (''en'')]] - jak stworzyć i edytować zachowanie AI
* [[Distributing content|Publikacja treści (''en'')]] - wszystko o serwerze dodatków
* [[Authoring tools|Narzędzia autorskie (''en'')]] - narzędzia pomocne przy tworzeniu kampanii
* [[Maintenance tools|Narzędzia (''en'')]] - narzędzia pomocne przy sprawdzaniu i utrzymywaniu kampanii

== Fanowskie dodatki ==
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.6-2.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.6-2-175.jpg]
<div class="thumbcaption">Edytor map</div></div>
</div>
Na [http://www.wesnoth.org/forum forum Wesnoth] można znaleźć zarówno wiele fanowskich dodatków jak i dyskusje o nowych i aktualnych projektach. Przykładowe działy na forum (po angielsku), które mogą okazać się przydatne lub/i interesujące:
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
Strony na wiki poświęcone fanowskim dodatkom:
* [[Guide_to_UMC_Content|Lista dodatków (''en'')]] - zawiera (niekompletną) listę dodatków stworzonych przez graczy
* [[Player_UMC_Reviews|Recenzje dodatków (''en'')]]

Jeśli chcesz puścić wodze fantazji bez intencji do tworzenia całej kampanii zajrzyj to tego tematu: [http://www.wesnoth.org/forum/viewtopic.php?t=17171 Abandoned campaigns]. Jest on w języku angielskim, ale zawiera dyskusję o porzuconych projektach, które można przejąć i dokończyć po swojemu. W tym celu warto też zajrzeć na [[Guide_to_UMC_Content|listę dodatków]]. Dokończenie zaczętej kampanii powinno być łatwiejsze i szybsze, szczególnie dla kogoś kto dopiero zaczyna swoją przygodę z WML.

== Świat Wesnoth ==
<div class="thumb tright"><div>
[https://www.wesnoth.org/wiki-images/wesnoth-map-1.12.jpg https://www.wesnoth.org/wiki-images/wesnoth-map-1.12-175.jpg]
<div class="thumbcaption">Mapa Wesnoth i okolic</div></div>
</div>
Nie wszystkie kampanie mają miejsce w uniwersum Wesnoth, ale większość tak. Jednakże trzeba przyznać, że kampanie, które rozgrywają się gdzieś w świecie Wesnoth mają swój niepowtarzalny klimat. Wystarczy wybrać epokę oraz miejsce na mapie, i opowiedzieć własną historię. Poniższe tematy zawierają podstawowe informacje na temat świata Wesnoth.
* [[Timeline of Wesnoth|Chronologia (''en'')]]
* [[Geography of Wesnoth|Geografia (''en'')]]
* [[Races|Rasy (''en'')]]
* [[WesnothFigures|Wybitne postacie (''en'')]]
* [[Poetry_of_Wesnoth|Poezja z Wesnoth (''en'')]]

== Przydatne linki ==
* [[ExternalUtilities|Zewnętrzne narzędzia(''en'')]] - trochę dodatkowych narzędzi przyspieszających pracę
* [[ReferenceWML|Kompendium WML (''en'')]] - zawiera informacje o wszystkich tagach WML i opisuje sposób ich użycia
* [[FAQ|FAQ (''en'')]] - masz pytanie? Śmiało!
* [http://addons.wesnoth.org Serwer z dodatkami (''en'')] - archiwum dodatków w wersji przeglądarkowej

[[Category:Polish]]

[[Category:Create|*]]

Create/zh-Hans

2024-11-08T03:11:33Z

Shiki: /* 我能创作什么，如何创作？ */ Swap broken editor image to older one

{{Translations}}
{| style="float:right"
|
__TOC__
|}
对创作自己的场景和战役感兴趣？韦诺最引人入胜的特点之一就是它的可扩展性。
玩家可以创建新地图、单位、种族、场景、图像、音乐甚至完整的战役。

接触游戏的”内部秘密“既是简单又是困难的；你只需要一个 UTF-8文本编辑器就足以创建你自己的世界。不过学习韦诺标记语言Wesnoth Markup Language (WML)很耗费精力。本章将会指引创作和发布你自己的内容的过程。

同时要注意的是，'''在韦诺核心的美工方面我们需要大量帮助。''' 我们正在工作的非即时项目表[http://www.wesnoth.org/forum/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= 列于此]. 如果你也把自己的问题放在里面，我们很乐于帮助你。

== 先读这个！ ==
在你修改或在添加任何东西前，去了解游戏如何储存和组织数据是很重要的。这篇文章会解释游戏目录结构，并介绍”用户数据userdata“ 目录。
* [[EditingWesnoth|编辑韦诺]]

== 我能创作什么，如何创作？==
[[File:Wesnoth-1.5.10-editor.png|thumb|韦诺之战地图编辑器]]

* [[WML_for_Complete_Beginners|WML教程]] - WML的介绍（未完成）
* [[BuildingMaps|地图]] - 地砖式的地形布局

* [[BuildingScenarios|场景]] - 场景就是让地图上的事情发生，让它可以玩
* [[BuildingCampaigns|战役]] - 把场景组织起来成为战役
* [[MultiplayerContent|多人游戏战役]] - 使战役用在多人游戏里 '''(过时)'''
* [[BuildingUnits|单位]]
* [[BuildingFactions|多人游戏派系和时代]]

* [[Create Art|美工]] - 和'''教程'''一起工作！
* [[Create Music|音乐]]
* [[Create Writing|写作]]
* [[WesnothTranslations|翻译]] - 进行韦诺的翻译工作
* [[Practical Guide to Modifying AI Behavior|电脑AI]] - 怎样创建和改变AI行为

* [[Distributing content|发布内容]] - 关于战役服务器
* [[Authoring tools|创作工具]] - 帮助你编写战役WML的工具
* [[Maintenance tools|维护工具]] - 帮你全面检查和维护战役的工具



== 其他人做了什么？ ==

在[http://www.wesnoth.org/forum 韦诺论坛]上有众多的多人游戏派系和时代、多人游戏地图和战役讨论。
* [http://forums.wesnoth.org/viewforum.php?f=19 派系和时代开发论坛]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 多人游戏开发论坛]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 场景和战役开发论坛]
* [[Faction|完整的派系列表]]

如果你不是想要创作一整个新战役，查看这个帖子[http://www.wesnoth.org/forum/viewtopic.php?t=17171 遗弃的战役]。你可以从中挑选一个然后完成它，比做一个全新的战役轻松得多。

== 韦诺的世界 ==
不是所有战役都发生在韦诺，不过大多数是。让战役发生在韦诺世界里一定很有味道。挑选一个时期或地图上的位置，再来创作故事。
* [[Timeline of Wesnoth/zh-Hans|韦诺时间线]]
* [[Geography of Wesnoth/zh-Hans|韦诺地理学]]
* [[Races|韦诺的生物种族]]
* [[Poetry of Wesnoth|韦诺的诗歌]]

== 杂项 ==
* [[ExternalUtilities|外部工具]] - 一些额外的工具帮助创作
* [[ReferenceWML|WML参考]] - 快捷链接
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|常见问题]] - 如果你有问题，发个帖子吧
* 插件服务器 [http://addons.wesnoth.org 网页界面] - 下载用户自制内容的一个可选方式

[[Category:Create|*]]

Create/pt BR

2024-11-08T03:08:25Z

Shiki: /* ¿Qué puedo crear, y cómo? */ Swap broken editor image to older one

{{Translations}}
{| style="float:right"
|
__TOC__
|}

Interessado em criar seus próprios cenários e campanhas? Uma das melhores ferramentas no jogo é sua capacidade de extensão. Jogadores podem criar novos mapas, unidades, raças, cenários, artes, músicas e campanhas. A utilização dos "extras" é ao mesmo tempo simples e complexa. Basta ter um editor de texto UTF-8 e todo um mundo novo se abre a você. Entretanto, aprender a Wesnoth Markup Language (WML) exige esforço. Esta seção busca lhe ajudar através do processo de criar e compartilhar suas criações.

Esta página em Português do Brasil é baseada na página em inglês, que tradicionalmente é a mais desenvolvida, tendo em vista que é a linguagem da maioria dos nossos colaboradores. Caso ainda restem dúvidas após ler a documentação em português, tente os textos em inglês.

== Leia isto primeiro! ==
Antes de modificar ou adicionar qualquer coisa, é importante entender como que o jogo armazena e organiza seus dados. Este artigo irá explicar a estrutura de diretórios do jogo e lhe apresentará o diretório com a ''userdata'':
* [[EditingWesnoth]]

== O que eu posso criar, e como? ==
[[File:Wesnoth-1.5.10-editor.png|thumb|Battle for Wesnoth map editor]]

A maioria dos links em inglês:

* [[BuildingMaps|Maps]] - o ''layout''' dos terrenos

* [[BuildingScenarios|Scenarios]] - um cenário faz as coisas acontecerem no mapa, tornando-o jogável
* [[BuildingCampaigns|Campaigns]] - Como colcoar todos os cenários em uma campanha
* [[MultiplayerContent|Multiplayer Campaigns]] - como fazer uma campanha funcionar no multiplayer '''(desatualizado)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]] '''(desatualizado)'''

* [[Create Art|Art]] - '''tutorial''' completo
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - Traduções do Wesnoth
** [[PortugueseTranslation|Tradução para o português do Brasil]] - Sempre necessitamos de mais ajuda

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - ferramenta para ajudar a escrever as campanhas WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns

== O que os outros estão fazendo? ==
Existem uma infinidade de pessoas colaborando com o desenvolvimento do jogo, em todas as áreas. Encontre-os [http://www.wesnoth.org/forum no fórum Wesnoth]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

Se você deseja utilizar sua capacidade criativa sem precisar criar uma campanha do zero, veja este tópico [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. Você poderá pegar uma campanha abandonada e completá-la, gastando muito menos energia e nos auxiliando a reciclar o "lixo".

== O mundo de Wesnoth ==
Nem todas as campanhas se passam em Wesnoth, mas a grande maioria sim. E todos os criadores são fortemente encorajados a criarem campanhas que se encaixem na História e Geografia de Wesnoth. Escolha um período e um local de Wesnoth e desenvolva sua história.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geografia de Wesnoth]]
* [[História de Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - Algumas ferramentas extras que auxiliam na criação de conteúdo
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ]] - Se possui alguma dúvida, pergunte.
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]
[[Category:Portuguese]]

Create/es

2024-11-08T03:06:16Z

Shiki: /* ¿Qué puedo crear, y cómo? */ Swap broken editor image to older one

{{Translations}}
{| style="float:right"
|
__TOC__
|}

¿Está interesado en crear sus propios escenarios y campañas? Una de las mejores características de Wesnoth consiste en sus posibilidades de extensión. Los jugadores pueden crear nuevos mapas, unidades, razas, escenarios, ilustraciones, música e incluso campañas enteras. El acceso a las "entrañas" del juego es simple, pero a la vez dificultoso; con tener un editor de texto UTF-8, ya posee todo lo necesario para crear su propio mundo. Sin embargo, aprender el Lenguaje de Marcadores de Wesnoth (''Wesnoth Markup Language'', WML) toma algo de esfuerzo. Esta sección le guiará a través del proceso de crear y distribuir su propio trabajo.
<br><br>
También le remarcamos que '''necesitamos mucha ayuda creando los elementos gráficos necesarios para el núcleo del juego.''' Los proyectos en los que estamos trabajando en la actualidad se encuentran [http://forums.wesnoth.org/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= aquí]. Le ayudaremos con agrado, siempre y cuando le haya dado un vistazo a los proyectos anteriormente.
<br><br>
<p><i>'''NOTA:''' La mayoría de los enlaces llevan a sitios completamente en el idioma inglés, salvo aquellos que indican lo contrario.</i></p>
== ¡Lea esto antes! ==

Antes de modificar o añadir algo, es importante que comprenda cómo el juego almacena y organiza sus datos. El siguiente artículo le explicará la estructura de carpetas del juego y le introducirá en el manejo del directorio ''userdata''.
* [[EditingWesnoth]]

== ¿Qué puedo crear, y cómo? ==
[[File:Wesnoth-1.5.10-editor.png|thumb|Editor de mapas de ''La Batalla por Wesnoth'']]

* [[BuildingMaps|Mapas]] - la disposición de las casillas de terreno

* [[BuildingScenarios/es|Escenarios]] - '''(<i>en español</i>)''' un escenario hace posible que sucedan eventos en un mapa, haciéndolo jugable
* [[BuildingCampaigns/es|Campañas]] - '''(<i>en español</i>)''' cómo colocar todo esto dentro de una campaña
* [[MultiplayerContent|Campañas para multijugadores]] - cómo hacer una campaña accesible en partidas multijugador
* [[BuildingUnits|Unidades]]
* [[BuildingFactions|Facciones y eras multijugador]]

* [[Create Art|Ilustraciones]] - Completo y con '''¡tutoriales!'''
* [[Create Music|Música]]
* [[Create Writing|Escritura]]
* [[WesnothTranslations|Traducciones]] - colabora traduciendo Wesnoth
* [[Practical Guide to Modifying AI Behavior|Inteligencia Artificial]] - cómo crear y modificar una rutina de la IA

* [[Distributing content|Distribuyendo el contenido]] - todo sobre el servidor de campañas
* [[Authoring tools|Herramientas de programación]] - herramientas para ayudar a escribir el código WML de los elementos
* [[Maintenance tools|Herramientas de mantenimiento]] - herramientas para ayudar a depurar el código y dar mantenimiento a las campañas


== ¿Qué han hecho otros? ==
Hay un gran número de mapas, facciones y eras multijugador, y discusiones sobre campañas, en el [http://www.wesnoth.org/forum foro de Wesnoth] (en inglés):
* [http://forums.wesnoth.org/viewforum.php?f=19 Foro de desarrollo de facciones y eras]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Foro de desarrollo de contenido multijugador]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Foro de desarrollo de escenarios y campañas]
* [[Faction|Lista completa de facciones]]

Si desea ser creador sin tener que inventar una campaña entera, visite el siguiente tema de [http://www.wesnoth.org/forum/viewtopic.php?t=17171 campañas abandonadas]. Ahí podrá seleccionar alguna de ellas y completarla, evitando pasar todo el trabajo de crear una nueva.

== El mundo de Wesnoth ==
No todas las campañas se desarrollan dentro de la trama de ''La Batalla por Wesnoth'', pero muchas de ellas sí que lo hacen. Existe cierta preponderancia hacia aquellas que se desarrollan dentro del mundo de Wesnoth. A continuación podrá encontrar información que le servirá para poder crear y relatar una nueva historia:
* [[Timeline of Wesnoth|Línea de tiempo histórica de Wesnoth]]
* [[Geography of Wesnoth|La geografía de Wesnoth]]
* [[Races|Las razas de las criaturas de Wesnoth]]
* [[Poetry of Wesnoth|La literatura de Wesnoth]]

== Miscelánea ==
* [[ExternalUtilities|Utilidades externas]] - herramientas adicionales que facilitan la creación
* [[ReferenceWML|Referencia al lenguaje WML]] - lenguaje de programación que se utiliza en ''La Batalla por Wesnoth''
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|Preguntas frecuentes]] - si tiene una, formúlela
* [http://addons.wesnoth.org Interfaz web] del SERVIDOR DE COMPLEMENTOS - una forma alternativa de descargar contenido de otros usuarios

[[Category:Create|*]]