The Battle for Wesnoth Wiki - User contributions [en]

UnitTypeWML

2026-08-02T18:02:48Z

Mentos987: race footprint update

{{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).
* '''footprints''': {{DevFeature1.19|26}} (optional) pick what footprint group of images this unit should have. E.g. ' footprints="swirling_pattern" ' will cause it to use images in the "..images\footsteps\swirling_pattern" folder. By default units will use the "images\footsteps\default" or the race footprint if such is assigned.
* '''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.
* '''[default_frame]''': {{DevFeature1.19|26}} (optional) adjusts the base image set by `image=`, using the same keys as a [frame] tag from AnimationWML (e.g. pixel offsets, drawing layer).
<div class="mw-collapsible mw-collapsed">
Example of [default_frame]:
<div class="mw-collapsible-content">
<pre>
[unit_type]
id=Fire Dragon
name= _ "Fire Dragon"
race=monster
image="units/monsters/fire-dragon.png"
[default_frame]
image="units/monsters/fire-dragon.png"
layer=50
y=-5
[/default_frame]
..
[/unit_type]
</pre>
</div>
</div>
* '''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''': ''(Version 1.12.0 and later only)'' 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.

== Base and variations ==
These create related unit types, for example the Walking Corpse's swimming, mounted, animal, etc. variations.

* {{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 and then this unit_type's WML overrides parts as documented in [[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.
* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit, this tag appears inside the base type's '''[unit_type]''' tag. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]].
** '''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 type, 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]''.

When merging the data, subtags can be deleted with ''__remove=yes'', as documented in ''[set_variables]''.

== Other tags ==
* '''[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].

* '''[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 [[AddonsWML#modify_unit_type|[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]]

UnitsWML

2026-08-02T18:00:45Z

Mentos987: footprint race wide added

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

There is a list with every mainline core [[Movement_types|movetype]].

=== [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.
* '''footprints''': {{DevFeature1.19|26}} (optional) pick what footprint group of images that units of this race should default to. E.g. ' footprints="swirling_pattern" ' will cause units to use images in the "..images\footsteps\swirling_pattern" folder. By default races will use the "..images\footsteps\default" footprint. If footprint is also assigned in the units cfg file then that will override this option for that specific unit.

=== [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]]

UnitTypeWML

2026-07-22T11:10:08Z

Mentos987: footprints added

{{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).
* '''footprints''': {{DevFeature1.19|26}} (optional) pick what footprint group of images this unit should have. E.g. ' footprints="swirling_pattern" ' will cause it to use images in the "..images\footsteps\swirling_pattern" folder. By default units will use the "humanoid" footprint.
* '''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.
* '''[default_frame]''': {{DevFeature1.19|26}} (optional) adjusts the base image set by `image=`, using the same keys as a [frame] tag from AnimationWML (e.g. pixel offsets, drawing layer).
<div class="mw-collapsible mw-collapsed">
Example of [default_frame]:
<div class="mw-collapsible-content">
<pre>
[unit_type]
id=Fire Dragon
name= _ "Fire Dragon"
race=monster
image="units/monsters/fire-dragon.png"
[default_frame]
image="units/monsters/fire-dragon.png"
layer=50
y=-5
[/default_frame]
..
[/unit_type]
</pre>
</div>
</div>
* '''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''': ''(Version 1.12.0 and later only)'' 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.

== Base and variations ==
These create related unit types, for example the Walking Corpse's swimming, mounted, animal, etc. variations.

* {{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 and then this unit_type's WML overrides parts as documented in [[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.
* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit, this tag appears inside the base type's '''[unit_type]''' tag. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]].
** '''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 type, 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]''.

When merging the data, subtags can be deleted with ''__remove=yes'', as documented in ''[set_variables]''.

== Other tags ==
* '''[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].

* '''[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 [[AddonsWML#modify_unit_type|[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]]

Creating Unit Art

2026-07-18T23:19:58Z

Mentos987: Comment about how to make huge units

Here's the information needed to start doing units art for Wesnoth. Please update the wiki with links to examples and other tips and tricks realted to unit art. This page started from [http://www.wesnoth.org/forum/viewtopic.php?p=104809#104809 this forum thread].

== The Medium ==

The medium used to create unit art is known as 'pixel art'. If you do not understand what pixel art is, or if you have only a general understanding of what it is, I suggest reading [http://www.pixeljoint.com/forum/forum_posts.asp?TID=11299 The Pixel Art Tutorial] by Cure. It is a tutorial comprised of a series of sequential forum posts on the www.pixeljoint.com forum and gives an in-depth overview of pixel art, explaining in detail what pixel art is and what it is not. Using other mediums (such as brush art) to create unit art is fine if you are creating unit art for [[Glossary|UMC]] add-ons (although it is still strongly recommended that you use pixel art for the sake of consistency with mainline units), but only units drawn in pure pixel art will be accepted into mainline.

== Basic unit image specifications ==

Wesnoth can only use two kinds of graphic files: PNGs, or JPEGs. JPEGs aren't suitable for unit images, because they can't store transparency data (and are lossy). Because of this, we always use PNGs for unit images.
*Final format: transparent PNG
** Color depth should be 32-bit (8 bits per RGBA channel). This may be listed for example as "PNG-32" or "8-bit RGBA".
** Be aware that "Indexed color", "color map", or "PNG-8" is a different format. Although it might work in a buggy way, we strongly recommend you not use these.
* Canvas size is 72 x 72 pixels (it can actually be slightly wider, and can fit in the area of a hex and its immediately surrounding tiles, but try not to do this if at all possible, because it has performance and graphical glitch issues).
*All but exceptionally large units should be contained in the hex if possible - the white in the template shown at right: http://forums.wesnoth.org/download/file.php?id=4334&type=.png
*Compare the size of your unit to the size of similar existing core units.
*<div style="float:right; padding:1ex; margin:1ex; border: thin dotted; font-size:80%;">http://forums.wesnoth.org/download/file.php?id=60404&type=.png</div>For oversize units, there are limitations with respect to the terrain system and asthetics. Sprites that are much bigger than the hex tend to end up getting partially obscured by terrain in inconvenient places and look bad. If you want everything to be always visible or believably covered then the black area in the picture is safe. You can usually exceed this to the left and right without much trouble, but going down is problematic with the great tree and stands out. The gold hex represents the hex the unit is actually in. Also, making units too large will hide those behind it, so even though the appearance will be correct in the entire black area, you will want to leave more than half of each of the hexes outside the gold one visible so as not to make other units vanish. [http://forums.wesnoth.org/viewtopic.php?f=23&t=38203&p=546367#p546331]
*For huge units that intrude on the hexes underneath them (sw,s,se) you can use the unit layer to force the centre hex above any terrain foreground (layer=50).
*Light comes from the artist's (''not'' the unit's!) upper right (for shading and highlights)
*Unit must look in the lower right (again, the artist's lower right, not the unit's) direction
*Units are centered horizontally
*Unit's feet are positioned around 55 pixel down from the top edge of the canvas, lower for taller units if necessary
*Shadows at 60 opacity, using a specific dark blue color (see [[Creating_Shadows_Under_Units|Creating Shadows Under Units]]).
*Outlines should be used, made with a darker, but similar color to what they're surrounding, this makes the unit feel bigger then the amount of pixels you'd use for the same with a black outline. Note that pure black (RGB #000000) should ''never'' be used to outline a sprite.
*Use consistent names for your files, beginning with the unit name, so that they are kept together when browsing the files. Try to imitate the naming scheme used for mainline units.

== Unit animation specifications ==

You can have as many frames for animations as you like, and in fact, for any given cue, you can have more than one animation, which will be randomly chosen by the game. Images and animations must be done for:
*base frame (1 frame)
*attack for each type (at least 4 frames, about 6 frames is optimal depending on the type of attack and the weapon(s) involved)
*directional attacks (generally are desired for any attack that's a straight motion, rather than a slash. I.e. spears and thundersticks)
*defense (usually 2 frames long not including the base frame, separate animations may be drawn for ranged and melee defense animations)

== Additional Notes ==

*Test early with different backgrounds. Go to your game terrain files, pick, say, 3 terrains, preferably with different colors, and have a look what they look like against the background, because that way if you have used alpha channels, it may look better in game than as the average standard sprite.

*Test your unit early in the game. Replacing an existing unit graphic with yours is the fastest way (be sure to make a copy of the originals so you don't lose them.)

*Test your unit next to mainline units in-game. This will help you ensure that your unit matches the style and proportions of the mainline units as closely as possible.

== See Also ==
* [[BuildingUnits]]
* [[Create]]
* [[Create Art and Music]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

UnitTypeWML

2026-07-18T23:09:46Z

Mentos987: "[default_frame]" added (recent merged PR)

{{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.
* '''[default_frame]''': {{DevFeature1.19|26}} (optional) adjusts the base image set by `image=`, using the same keys as a [frame] tag from AnimationWML (e.g. pixel offsets, drawing layer).
<div class="mw-collapsible mw-collapsed">
Example of [default_frame]:
<div class="mw-collapsible-content">
<pre>
[unit_type]
id=Fire Dragon
name= _ "Fire Dragon"
race=monster
image="units/monsters/fire-dragon.png"
[default_frame]
image="units/monsters/fire-dragon.png"
layer=50
y=-5
[/default_frame]
..
[/unit_type]
</pre>
</div>
</div>
* '''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''': ''(Version 1.12.0 and later only)'' 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.

== Base and variations ==
These create related unit types, for example the Walking Corpse's swimming, mounted, animal, etc. variations.

* {{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 and then this unit_type's WML overrides parts as documented in [[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.
* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit, this tag appears inside the base type's '''[unit_type]''' tag. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]].
** '''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 type, 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]''.

When merging the data, subtags can be deleted with ''__remove=yes'', as documented in ''[set_variables]''.

== Other tags ==
* '''[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].

* '''[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 [[AddonsWML#modify_unit_type|[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]]

InterfaceActionsWML

2026-07-17T13:25:18Z

Mentos987: /* [move_units_fake] */ typo

{{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 {{DevFeature1.19|9}} working again
* '''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 center of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' To position a small image somewhere other than the center, [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image). The image is centered since {{DevFeature1.17|7}}, previously the images were aligned to the top-left; however this difference doesn't affect any image BLITted onto blank-hex.png, as that is the same size as a hex.)''
* '''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 #1219]). ''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''
* '''name''' an id that can be used to remove the item.
* '''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.
* '''submerge''': float, between 0 and 1: specifies how much of the image should be submerged. Gets multiplied with [[TerrainWML|[terrain]]]<nowiki/>submerge. Default 0.
* '''z_order''': float: defines the order the items get drawn in. Default 0.
* '''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.
* '''parallel''': {{DevFeature1.19|26}} If yes (default no), will cause the movement animations of the different fake units to execute in parallel rather than one at a time.
* '''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
<div class="mw-collapsible mw-collapsed">
'''Example of [move_units_fake] code:'''
<div class="mw-collapsible-content">
[move_units_fake]
parallel=yes
[fake_unit]
type="Orcish Slurbow"
side=2
x=8,15,39,12
y=26,25,10,10
[/fake_unit]
[fake_unit]
type="Orcish Grunt"
side=2
x=5,15
y=27,27
[/fake_unit]
[/move_units_fake]
</div>
</div>

=== [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 = 14): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 3): 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

Note that [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] also rebuilds affected units so any changes done via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset, unlike when using [remove_unit_overlay]

=== [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 putting the mouse over 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]]

InterfaceActionsWML

2026-07-16T19:10:24Z

Mentos987: Example for [move_units_fake]

{{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 {{DevFeature1.19|9}} working again
* '''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 center of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' To position a small image somewhere other than the center, [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image). The image is centered since {{DevFeature1.17|7}}, previously the images were aligned to the top-left; however this difference doesn't affect any image BLITted onto blank-hex.png, as that is the same size as a hex.)''
* '''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 #1219]). ''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''
* '''name''' an id that can be used to remove the item.
* '''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.
* '''submerge''': float, between 0 and 1: specifies how much of the image should be submerged. Gets multiplied with [[TerrainWML|[terrain]]]<nowiki/>submerge. Default 0.
* '''z_order''': float: defines the order the items get drawn in. Default 0.
* '''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.
* '''parallel''': {{DevFeature1.19|26}} If yes (default no), will cause the movement animations of the different fake units to execute in parallel rather than one at a time."
* '''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
<div class="mw-collapsible mw-collapsed">
'''Example of [move_units_fake] code:'''
<div class="mw-collapsible-content">
[move_units_fake]
parallel=yes
[fake_unit]
type="Orcish Slurbow"
side=2
x=8,15,39,12
y=26,25,10,10
[/fake_unit]
[fake_unit]
type="Orcish Grunt"
side=2
x=5,15
y=27,27
[/fake_unit]
[/move_units_fake]
</div>
</div>

=== [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 = 14): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 3): 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

Note that [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] also rebuilds affected units so any changes done via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset, unlike when using [remove_unit_overlay]

=== [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 putting the mouse over 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]]

InterfaceActionsWML

2026-07-16T18:59:26Z

Mentos987: parallel animation option for move_units_fake

{{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 {{DevFeature1.19|9}} working again
* '''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 center of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' To position a small image somewhere other than the center, [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image). The image is centered since {{DevFeature1.17|7}}, previously the images were aligned to the top-left; however this difference doesn't affect any image BLITted onto blank-hex.png, as that is the same size as a hex.)''
* '''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 #1219]). ''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''
* '''name''' an id that can be used to remove the item.
* '''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.
* '''submerge''': float, between 0 and 1: specifies how much of the image should be submerged. Gets multiplied with [[TerrainWML|[terrain]]]<nowiki/>submerge. Default 0.
* '''z_order''': float: defines the order the items get drawn in. Default 0.
* '''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.
* '''parallel''': {{DevFeature1.19|26}} If yes (default no), will cause the movement animations of the different fake units to execute in parallel rather than one at a time."
* '''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 = 14): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 3): 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

Note that [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] also rebuilds affected units so any changes done via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset, unlike when using [remove_unit_overlay]

=== [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 putting the mouse over 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]]

ImagePathFunctions

2025-09-29T17:24:07Z

Mentos987: /* PAD: Pad function */

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like
"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"
would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

A color palette can be either the attribute name from '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' (like magenta) or a comma separated list of hex color values.

=== RC: Re-Color function ===
May be used to change some colors in an image. It is possible to use ''RC'' more than once on the same image, with different source palettes.

'''~RC(''' ''source color palette'' '''>''' ''destination color range'' ''')'''

==== source color palette ====
The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

* '''magenta''' - the 19 colors described in [[Team_Color_Shifting]]
* '''ellipse_red''' - all 255 colors with RGB value (n,0,0)
* '''flag_green''' - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) '''red''', '''green''' and any other defined '''[color_range]'''; however the set of RGB values for those aren't guaranteed. Using '''red''' instead of '''ellipse_red''' might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

==== destination color range ====
This is the second parameter, signifying the ID of a color range defined in the file [http://github.com/wesnoth/wesnoth/blob/master/data/core/team-colors.cfg data/core/team-colors.cfg] (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from [[GameConfigWML#Color_Palettes]]; note that RC does not use the fourth color for anything).

For this destination color range, using '''red''' or '''green''' makes sense.

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The following example replaces a few of the '''magenta''' pixels with green ones:

misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate function ===
May be used to rotate an image.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear interpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-paste-extend ==

=== BLIT: Blit function ===
Blit (superimpose) the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. If missing assume (0,0).

=== CROP: Crop function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== CROP_TRANSPARENCY ===
{{devfeature1.17|26}}
Removes any transparent padding from around an image.

'''~CROP_TRANSPARENCY()'''

=== PAD: Pad function===
{{devfeature1.19|17}}
Extends side(s) of an image with transparent pixels.

'''~PAD(..)'''
*called with a single number like ''~PAD(10)'' and it will add a 10 pixel padding to every side.
*called with keys (top, t, right, r, bottom, b, left, l) like ''~PAD(bottom=10, t=5)'' and it will pad those sides by that much.
Can be used to create a fake offset by padding one side of an image in order to push it in the opposite direction.

=== MASK: Mask function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

The context object for the formula is a '''[[#CHAN:_General_function|pixel object]]'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== CHAN: General function ===

{{DevFeature1.13|7}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''~CHAN(formula, formula, formula)'''

The context object for each of the formulas is a '''pixel object''' with the following properties:

* '''x''', '''y''': coordinates of the pixel, from the top left
* '''u''', '''v''': {{DevFeature1.15|0}} normalized coordinates in the range [0,1]
* '''width''', '''height''': size of the image canvas
* '''red''', '''green''', '''blue''', '''alpha''': components of the pixel colour

=== DARKEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

=== Pseudo IPFs ===

The following functions are ignored by the IPF image modification module, but used by other Wesnoth components. They only work in special areas.

==== NO_TOD_SHIFT: Disabling ToD ====

{{DevFeature1.13|8}}

This is used by the terrain renderer and prevents terrain and item images from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

'''~NO_TOD_SHIFT()'''

==== RIGHT: Display portraits on the right ====

'''''([[DevFeature|Version 1.5.8 and later only]])'''''

This is used by the [[InterfaceActionsWML#.5Bmessage.5D|'''[message]''']] interface action and can be used to show a portrait on the right side of the screen.

'''~RIGHT()'''

== Creating an image file from IPFs ==

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option ''--render-image'.

Assuming you find a way to open your computer's terminal:
wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:
"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:
* Experimenting with Image Path Functions. If none of the images are from an add-on, adding ''--noaddons'' will speed this up.
* If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
* In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …
== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string
* [https://irydacea.me/projects/wespal Wespal] - Tool to preview unit recoloring. Covers the effects of the [[#RC:_Re-Color_Function|RC]], [[#TC: Team-Color Function|TC]] and [[#PAL:_Palette-switch_Function|PAL]] functions.
* [https://github.com/wesnoth/wesnoth/blob/master/src/image_modifications.cpp src/image_modifications.cpp] - file where IPFs are implemented
[[Category:WML Reference]]

ImagePathFunctions

2025-09-29T17:14:05Z

Mentos987: /* PAD: Pad function */

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like
"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"
would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

A color palette can be either the attribute name from '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' (like magenta) or a comma separated list of hex color values.

=== RC: Re-Color function ===
May be used to change some colors in an image. It is possible to use ''RC'' more than once on the same image, with different source palettes.

'''~RC(''' ''source color palette'' '''>''' ''destination color range'' ''')'''

==== source color palette ====
The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

* '''magenta''' - the 19 colors described in [[Team_Color_Shifting]]
* '''ellipse_red''' - all 255 colors with RGB value (n,0,0)
* '''flag_green''' - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) '''red''', '''green''' and any other defined '''[color_range]'''; however the set of RGB values for those aren't guaranteed. Using '''red''' instead of '''ellipse_red''' might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

==== destination color range ====
This is the second parameter, signifying the ID of a color range defined in the file [http://github.com/wesnoth/wesnoth/blob/master/data/core/team-colors.cfg data/core/team-colors.cfg] (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from [[GameConfigWML#Color_Palettes]]; note that RC does not use the fourth color for anything).

For this destination color range, using '''red''' or '''green''' makes sense.

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The following example replaces a few of the '''magenta''' pixels with green ones:

misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate function ===
May be used to rotate an image.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear interpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-paste-extend ==

=== BLIT: Blit function ===
Blit (superimpose) the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. If missing assume (0,0).

=== CROP: Crop function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== CROP_TRANSPARENCY ===
{{devfeature1.17|26}}
Removes any transparent padding from around an image.

'''~CROP_TRANSPARENCY()'''

=== PAD: Pad function===
{{devfeature1.19|16}}
Extends side(s) of an image with transparent pixels.

'''~PAD(..)'''
*called with a single number like ''~PAD(10)'' and it will add a 10 pixel padding to every side.
*called with keys (top, t, right, r, bottom, b, left, l) like ''~PAD(bottom=10, t=5)'' and it will pad those sides by that much.
Can be used to create a fake offset by padding one side of an image in order to push it in the opposite direction.

=== MASK: Mask function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

The context object for the formula is a '''[[#CHAN:_General_function|pixel object]]'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== CHAN: General function ===

{{DevFeature1.13|7}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''~CHAN(formula, formula, formula)'''

The context object for each of the formulas is a '''pixel object''' with the following properties:

* '''x''', '''y''': coordinates of the pixel, from the top left
* '''u''', '''v''': {{DevFeature1.15|0}} normalized coordinates in the range [0,1]
* '''width''', '''height''': size of the image canvas
* '''red''', '''green''', '''blue''', '''alpha''': components of the pixel colour

=== DARKEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

=== Pseudo IPFs ===

The following functions are ignored by the IPF image modification module, but used by other Wesnoth components. They only work in special areas.

==== NO_TOD_SHIFT: Disabling ToD ====

{{DevFeature1.13|8}}

This is used by the terrain renderer and prevents terrain and item images from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

'''~NO_TOD_SHIFT()'''

==== RIGHT: Display portraits on the right ====

'''''([[DevFeature|Version 1.5.8 and later only]])'''''

This is used by the [[InterfaceActionsWML#.5Bmessage.5D|'''[message]''']] interface action and can be used to show a portrait on the right side of the screen.

'''~RIGHT()'''

== Creating an image file from IPFs ==

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option ''--render-image'.

Assuming you find a way to open your computer's terminal:
wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:
"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:
* Experimenting with Image Path Functions. If none of the images are from an add-on, adding ''--noaddons'' will speed this up.
* If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
* In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …
== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string
* [https://irydacea.me/projects/wespal Wespal] - Tool to preview unit recoloring. Covers the effects of the [[#RC:_Re-Color_Function|RC]], [[#TC: Team-Color Function|TC]] and [[#PAL:_Palette-switch_Function|PAL]] functions.
* [https://github.com/wesnoth/wesnoth/blob/master/src/image_modifications.cpp src/image_modifications.cpp] - file where IPFs are implemented
[[Category:WML Reference]]

ImagePathFunctions

2025-09-29T17:10:04Z

Mentos987: /* Cut-and-paste */

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like
"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"
would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

A color palette can be either the attribute name from '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' (like magenta) or a comma separated list of hex color values.

=== RC: Re-Color function ===
May be used to change some colors in an image. It is possible to use ''RC'' more than once on the same image, with different source palettes.

'''~RC(''' ''source color palette'' '''>''' ''destination color range'' ''')'''

==== source color palette ====
The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

* '''magenta''' - the 19 colors described in [[Team_Color_Shifting]]
* '''ellipse_red''' - all 255 colors with RGB value (n,0,0)
* '''flag_green''' - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) '''red''', '''green''' and any other defined '''[color_range]'''; however the set of RGB values for those aren't guaranteed. Using '''red''' instead of '''ellipse_red''' might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

==== destination color range ====
This is the second parameter, signifying the ID of a color range defined in the file [http://github.com/wesnoth/wesnoth/blob/master/data/core/team-colors.cfg data/core/team-colors.cfg] (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from [[GameConfigWML#Color_Palettes]]; note that RC does not use the fourth color for anything).

For this destination color range, using '''red''' or '''green''' makes sense.

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The following example replaces a few of the '''magenta''' pixels with green ones:

misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate function ===
May be used to rotate an image.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear interpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-paste-extend ==

=== BLIT: Blit function ===
Blit (superimpose) the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. If missing assume (0,0).

=== CROP: Crop function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== CROP_TRANSPARENCY ===
{{devfeature1.17|26}}
Removes any transparent padding from around an image.

'''~CROP_TRANSPARENCY()'''

=== PAD: Pad function===
{{devfeature1.19|16}}
Extends side(s) of an image with transparent pixels.

'''~PAD(..)'''
*called with a single number like ~PAD(10) and it will add a 10 pixel padding to every side.
*called with keys (top, t, right, r, bottom, b, left, l) like ~PAD(bottom=10, t=5) and it will pad those sides by that much.
*can be used to create a fake offset by padding one side of an image in order to push it in the opposite direction.

=== MASK: Mask function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

The context object for the formula is a '''[[#CHAN:_General_function|pixel object]]'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== CHAN: General function ===

{{DevFeature1.13|7}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''~CHAN(formula, formula, formula)'''

The context object for each of the formulas is a '''pixel object''' with the following properties:

* '''x''', '''y''': coordinates of the pixel, from the top left
* '''u''', '''v''': {{DevFeature1.15|0}} normalized coordinates in the range [0,1]
* '''width''', '''height''': size of the image canvas
* '''red''', '''green''', '''blue''', '''alpha''': components of the pixel colour

=== DARKEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

=== Pseudo IPFs ===

The following functions are ignored by the IPF image modification module, but used by other Wesnoth components. They only work in special areas.

==== NO_TOD_SHIFT: Disabling ToD ====

{{DevFeature1.13|8}}

This is used by the terrain renderer and prevents terrain and item images from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

'''~NO_TOD_SHIFT()'''

==== RIGHT: Display portraits on the right ====

'''''([[DevFeature|Version 1.5.8 and later only]])'''''

This is used by the [[InterfaceActionsWML#.5Bmessage.5D|'''[message]''']] interface action and can be used to show a portrait on the right side of the screen.

'''~RIGHT()'''

== Creating an image file from IPFs ==

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option ''--render-image'.

Assuming you find a way to open your computer's terminal:
wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:
"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:
* Experimenting with Image Path Functions. If none of the images are from an add-on, adding ''--noaddons'' will speed this up.
* If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
* In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …
== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string
* [https://irydacea.me/projects/wespal Wespal] - Tool to preview unit recoloring. Covers the effects of the [[#RC:_Re-Color_Function|RC]], [[#TC: Team-Color Function|TC]] and [[#PAL:_Palette-switch_Function|PAL]] functions.
* [https://github.com/wesnoth/wesnoth/blob/master/src/image_modifications.cpp src/image_modifications.cpp] - file where IPFs are implemented
[[Category:WML Reference]]