The Battle for Wesnoth Wiki - User contributions [en]

GrammarWML

2026-04-25T13:12:13Z

Bssarkar: /* Help Markup */ typofix: XMl -> XML

{{WML Tags}}
This page contains a formal grammar of the Wesnoth domain-specific languages, including WML and its preprocessor. It does not attempt to capture any of the ways that the Wesnoth engine may interpret a string, such as WML variable substitution. It also doesn't fully capture the potential consequences of macros, for example the use of unbalanced WML tags. The syntax used is [https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form Extended Backus-Naur form]:

* Every rule is of the form <tt>nonterminal = rule ;</tt> with a terminating semicolon.
* Comments are enclosed in <tt>(* these *)</tt>.
* Literal values are enclosed in either double or single quotes. There is no special syntax inside quotes.
* <tt>(...)</tt> can be used for grouping.
* <tt>N * A</tt> where N is a number means "exactly N instances of A".
* <tt>[A]</tt> means "zero or one instances of A".
* <tt>{A}</tt> means "zero or more instances of A".
* <tt>A , B</tt> means "A followed by B".
* <tt>A | B</tt> means "either A or B".
* <tt>A - B</tt> means "A but not B".]
* Some special values are enclosed in <tt>?...?</tt>. This document uses the following special values:
** <tt>?newline?</tt>, <tt>?tab?</tt>, and <tt>?space?</tt> represent the named non-printable characters.
** <tt>?unicode?</tt> represents any valid Unicode character.
** <tt>?digit?</tt> represents any decimal digit.
** <tt>?hexdigit?</tt> represents any hexadecimal digit.
** <tt>?letter?</tt> represents any ASCII Latin letter in either uppercase or lowercase.

== WML Preprocessor ==

The WML preprocessor knows little of the grammar of the WML language itself; it is primarily just a text-substitution engine. Currently this is just a draft and may not be entirely accurate.

<syntaxhighlight lang=ebnf>
preproc_doc = {preproc_directive | preproc_line} ;
preproc_directive = simple_directive | macro_definition | if_block ;
preproc_line = {preproc_text} , ['<'] , [comment] , ?newline? ;
preproc_text = preproc_char | '<' , preproc_char | '<<' , macro_free_text , '>>' | macro_inclusion ;
preproc_char = char - ('<' | '{' | '#' | ?newline?) ;
macro_free_text = {macro_free_char | '>' , macro_free_char} ;
macro_free_char = char - '>' ; (* Note: this can include newlines! *)
macro_inclusion = '{' , macro_name , {req_ws , macro_argument} , '}' ;
macro_name = macro_name_char , {macro_name_char}
macro_name_char = char - ('}' | ws) ;
macro_argument = macro_component , {macro_component}
macro_component = macro_name
| macro_inclusion
| '(' , [preproc_doc] , ')'
| ['_'] , opt_ws , '"' , {quoted_char | macro_inclusion} , '"'
| '<<' , macro_free_text , '>>'
;
quoted_char = char - ( '}' | '"' ) | '""' ;
comment = opt_ws , '#' , {comment_char} , ?newline? ;
comment_char = char - ?newline? ;
ws = ?space? | ?tab?
opt_ws = {ws}
req_ws = ws , {ws}
simple_directive = '#undef' , req_ws , macro_name , opt_ws , ?newline?
| ('#warning' | '#error') req_ws , {comment_char} , ?newline? ;
macro_definition = '#define' , req_ws , macro_name , {req_ws macro_name} , ?newline? , {opt_arg_definition} , {macro_content} , '#enddef' , ?newline? ;
macro_content = simple_directive | if_block | preproc_line ;
opt_arg_definition = '#arg' , req_ws , macro_name , ?newline? , {macro_content} , '#endarg' , ?newline? ;
if_block = (ifdef_header | ifver_header | ifhave_header) , ?newline? , preproc_doc ['#else' , ?newline? , preproc_doc] '#endif' , ?newline? ;
ifdef_header = ('#ifdef' | '#ifndef') , req_ws , macro_name ;
ifver_header = ('#ifver' | '#ifnver') , req_ws , macro_name , opt_ws , comparison_op , opt_ws , version_string ;
ifhave_header = ('#ifhave' | '#ifnhave') , req_ws , comment_char ;
comparison_op = '<' | '<=' | '==' | '!=' | '>=' | '>' ;
version_string = integer , ['.' , integer] ;
integer = ?digit? , {?digit?} ;
</syntaxhighlight>

== WML ==

This grammar describes WML '''after''' the preprocessor is finished with it, and as such does not account for macros, preprocessor directives, or comments. It also assumes tokenization has already occurred and thus does not specify whitespace, except for newlines. Note that it omits the requirement for opening and closing tags to match.

<syntaxhighlight lang=ebnf>
wml_doc = {wml_tag | wml_attribute} ;
wml_tag = '[' , ['+'] , wml_name , ']' , wml_doc , '[/' , wml_name , ']' ;
wml_name = wml_id_char , {wml_id_char} ;
wml_attribute = [textdomain] , wml_key_sequence , '=' , wml_value , ?newline? ;
wml_key_sequence = wml_name , {',' , wml_name} ;
wml_value = wml_value_component , {'+' , [?newline? , [textdomain]] , wml_value_component} ;
wml_value_component = text | ['_'] , (string | raw_string) ;
text = {?unicode? - '+' | '"' | ?newline?} ;
string = '"' . {?unicode? - '"' | '""'} , '"' ;
raw_string = '<<' , {?unicode? - '>' | '>' , ?unicode? - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = ?letter? | ?digit? | '_' ;
domain_char = wml_id_char | '-' ;
</syntaxhighlight>

== WML Substitutions ==

This grammar describes the syntax of WML substitutions, the syntax used to specify that variables should be substituted into the value of a WML attribute. The grammar here describes a single placeholder, without regard to the fact that they can be nested. Thus, parsing a string using this grammar would only succeed if done from right to left ''while'' performing the substitutions.

<syntaxhighlight lang=ebnf>
wml_substitution = wml_var | wml_formula | '$|' ;
wml_var = '$' , wml_var_path , [wml_var_default | '|'] ;
wml_var_path = {wml_var_name , [wml_var_index] , '.'} , wml_var_name ;
wml_var_name = wml_id_char, {wml_id_char} ; (* wml_id_char is defined in the WML grammar, above *)
wml_var_index = '[' , ?digit? , {?digit?} , ']' ;
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = ?unicode? - '|' ;
wml_formula = '$' , '(' , wfl_document , ')' ;
</syntaxhighlight>

== Context-free Grammars ==

This grammar describes the syntax of a [[Context-free grammar]] used for random text generation.

<syntaxhighlight lang=ebnf>
grammar = production , {production} ;
production = symbol , '=' , alternative , {'|' , alternative} , ?newline? ;
symbol = symbol_char , {symbol_char} ;
symbol_char = ?letter? | ?digit? | '_' ; (* Unsure on this, need to check it *)
alternative = {terminal} ;
terminal = '{' , symbol , '}' | '{!}' | '{(}' | '{)}' | (?unicode? - '}') ;
</syntaxhighlight>

== Wesnoth Formula Language ==

This grammar describes the syntax of the [[Wesnoth Formula Language]]. Though it specifies the format of comments and file markers, they are not integrated into the main grammar since it treats the equivalently to whitespace. The grammar may not be completely accurate to the actual in-game parser.

<syntaxhighlight lang=ebnf>
wfl_comment = '#' , {wfl_comment_char} , '#' ;
wfl_comment_char = ?unicode? - '#' ;
wfl_file_run = 'wfl' , wfl_string , wfl_file_content , 'wflend' ;
wfl_file_content = {?any token? - 'wflend'} ;
wfl_document = {wfl_function_definition} , wfl_formula ;
wfl_function_definition = 'def' , wfl_name , '(' , [wfl_function_args] , ')' , wfl_formula , ';' ;
wfl_function_args = wfl_function_arg , {',' , wfl_function_arg} ;
wfl_function_arg = wfl_name , ['*'] ;
wfl_formula = ['not'] , where_expression | bracketed_expression ;
bracketed_expression = '(' , wfl_formula , ')' ;
where_expression = (boolean_or_expression | bracketed_expression) , {'where' , wfl_variables} ;
wfl_variables = wfl_variable , {',' , wfl_variable} ;
wfl_variable = wfl_name , '=' , wfl_formula ;
boolean_or_expression = (boolean_and_expression | bracketed_expression) , {'or' , wfl_formula} ;
boolean_and_expression = (comparison_expression | bracketed_expression) , {'and' , wfl_formula} ;
comparison_expression = (containment_expression | bracketed_expression) , {comparison_op , wfl_formula} ;
comparison_op = '=' | '!=' | '<' | '>' | '<=' | '>=' ;
containment_expression = (range_expression | bracketed_expression) , {'in' , wfl_formula} ;
range_expression = (additive_expression | bracketed_expression) , {'~' , wfl_formula} ;
additive_expression = [negation_op] , (multiplicative_expression | bracketed_expression) , {additive_op , wfl_formula} ;
negation_op = '-' | '+' ;
additive_op = '-' | '+' | '..' ;
multiplicative_expression := (exponent_expression | bracketed_expression) , {multiplicative_op , wfl_formula} ;
muliplicative_op = '*' | '/' | '%' ;
exponent_expression = {wfl_formula , '^'} , (dice_expression | bracketed_expression) ;
dice_expression = (dot_expression | bracketed_expression) , {'d' , wfl_formula} ;
dot_expression = (wfl_value | bracketed_expression) , {'.' , wfl_formula} ;
wfl_value = 'functions' | wfl_name | wfl_number | wfl_string | wfl_container | wfl_function_call ;
wfl_name = wfl_id_char , {wfl_id_char} ;
wfl_id_char = ?letter? | '_' ; (* Note: digits are NOT allowed! *)
wfl_number = ?digit? , {?digit?} , ['.' , ?digit? , {?digit?}] ;
wfl_string = "'" , {wfl_string_char | wfl_string_subst | wfl_string_escape} , "'" ;
wfl_string_char = ?unicode? - ("'" | "[") ;
wfl_string_subst = '[' , wfl_formula , ']' ;
wfl_string_escape = "[']" | '[(]' | '[)]' ;
wfl_container = '[' , ['->' | wfl_expression_list | wfl_key_value_list] , ']' ;
wfl_expression_list = wfl_formula , {',' , wfl_formula} ;
wfl_key_value_list = wml_key_value , {',' , wml_key_value} ;
wml_key_value = wfl_formula , '->' , wfl_formula ;
wfl_function_call = wfl_name , '(' , [wfl_expression_list] , ')' ;
</syntaxhighlight>

== Help Markup ==

This grammar defines the [[help markup]] used in Wesnoth help topics and GUI2 rich labels. It's ''almost'' HTML and ''almost'' XML but not quite either.

<syntaxhighlight lang=ebnf>
document = {text | tag} ;
text = {literal | entity | escape} ;
literal = ?unicode? - ('<' , '&' , '\') ;
escape = '\' , ?unicode? ;
entity = '&#' , ?digit? , {?digit?} , ';'
| '&#x' , ?hexdigit? , {?hexdigit?} , ';'
| '&' , name , ';'
;
tag = '<' , name , {attribute} , '/' '>' (* Self-closing tag, XML-style *)
| '<' , name , {attribute} , '>' , document , '</' , name , '>' (* HTML-style tag, nestable *)
| '<' , name , '>' , {attribute} , [text] , '</' , name , '>' (* Old-style tag, not nestable *)
;
attribute = name , ['=' , attribute_value] ;
attribute_value = {?unicode? - ("'" | '"' | ?space?)} (* Unquoted value *)
| "'" , text - "'" , "'"
| '"' , text - '"' , '"'
;
name = name_char , {name_char} ;
name_char = ?letter? | ?digit? | '_'
</syntaxhighlight>

== Progressive Values ==

This grammar describes progressive strings and numbers used by animation frames.

<syntaxhighlight lang=ebnf>
range_integer = digits , ['~' , digits] , [timing] ;
progressive_integer = range_integer , {',' , range_integer} ;

range_real = digits , ['.' , digits] , ['~' , digits , [',' , digits]] , [timing] ;
progressive_real = range_real , {',' , range_real} ;

range_string = {literal | expansion_list} , [timing | ':' , expansion_list] ;
progressive_string = range_string , {',' , range_string} ;
literal = ?unicode? - ('[' | ',' | ':') ; (* Colon actually might be permitted, not sure *)
expansion_list = '[' , expansion , {',' , expansion} , ']' ;
expansion = range_integer | digits , '*' , digits ;

digits = digit , {digit} ;
timing = ':' , digits ;
</syntaxhighlight>

[[Category:WML Reference]]

CompatibilityBreakingChanges

2026-04-13T11:36:24Z

Bssarkar: /* 1.19.22 */

This lists removed WML functionality and helpful hints for avoiding pitfalls.

The previous list is available [https://forums.wesnoth.org/viewtopic.php?t=58532 here].

== Compatibility breaking changes between 1.18 and 1.19/1.20 ==
* The following macros were removed ([https://github.com/wesnoth/wesnoth/pull/11126 #11126])
** EARLY_FINISH_BONUS_NOTE
** NO_EARLY_FINISH_BONUS_NOTE
** NO_GOLD_CARRYOVER_NOTE
** NEW_GOLD_CARRYOVER_NOTE_100
** NEW_GOLD_CARRYOVER_NOTE_40
** NEW_GOLD_CARRYOVER_NOTE_20
** MISSILE_FRAME_FIREBALL
** MESSAGE
** STORY_PART_SPEECH
** LOYAL_UNDEAD_UNIT
** ON_SIGHTING
** MAKE_AI_SIDE_PERSISTENT
** DRAKE_FLYING_ANIM
** NO_INTERRUPT_NO_UNDO
** ENABLE_NIGHTBLADE

CompatibilityBreakingChanges

2026-04-13T11:21:09Z

Bssarkar: /* Removed (#11126) */

== 1.19.22 ==
=== Removed macros ===
==== Removed ([https://github.com/wesnoth/wesnoth/pull/11126 #11126]) ====
* EARLY_FINISH_BONUS_NOTE
* NO_EARLY_FINISH_BONUS_NOTE
* NO_GOLD_CARRYOVER_NOTE
* NEW_GOLD_CARRYOVER_NOTE_100
* NEW_GOLD_CARRYOVER_NOTE_40
* NEW_GOLD_CARRYOVER_NOTE_20
* MISSILE_FRAME_FIREBALL
* MESSAGE
* STORY_PART_SPEECH
* LOYAL_UNDEAD_UNIT
* ON_SIGHTING
* MAKE_AI_SIDE_PERSISTENT
* DRAKE_FLYING_ANIM
* NO_INTERRUPT_NO_UNDO
* ENABLE_NIGHTBLADE

CompatibilityBreakingChanges

2026-04-13T11:20:40Z

Bssarkar: /* Removed in #11126 */

== 1.19.22 ==
=== Removed macros ===
==== Removed (#11126) ====
* EARLY_FINISH_BONUS_NOTE
* NO_EARLY_FINISH_BONUS_NOTE
* NO_GOLD_CARRYOVER_NOTE
* NEW_GOLD_CARRYOVER_NOTE_100
* NEW_GOLD_CARRYOVER_NOTE_40
* NEW_GOLD_CARRYOVER_NOTE_20
* MISSILE_FRAME_FIREBALL
* MESSAGE
* STORY_PART_SPEECH
* LOYAL_UNDEAD_UNIT
* ON_SIGHTING
* MAKE_AI_SIDE_PERSISTENT
* DRAKE_FLYING_ANIM
* NO_INTERRUPT_NO_UNDO
* ENABLE_NIGHTBLADE

CompatibilityBreakingChanges

2026-04-13T11:19:05Z

Bssarkar: List removed macros in #11126

== 1.19.22 ==
=== Removed macros ===
==== Removed in #11126 ====
* `EARLY_FINISH_BONUS_NOTE`
* `NO_EARLY_FINISH_BONUS_NOTE`
* `NO_GOLD_CARRYOVER_NOTE`
* `NEW_GOLD_CARRYOVER_NOTE_100`
* `NEW_GOLD_CARRYOVER_NOTE_40`
* `NEW_GOLD_CARRYOVER_NOTE_20`
* `MISSILE_FRAME_FIREBALL`
* `MESSAGE`
* `STORY_PART_SPEECH`
* `LOYAL_UNDEAD_UNIT`
* `ON_SIGHTING`
* `MAKE_AI_SIDE_PERSISTENT`
* `DRAKE_FLYING_ANIM`
* `NO_INTERRUPT_NO_UNDO`
* `ENABLE_NIGHTBLADE`

User:Bssarkar

2026-04-11T11:42:46Z

Bssarkar: draft deprecation policy

== Revised Deprecation Policy ==

== Goals ==
* Keep the codebase clean and maintainable.
* Provide clear expectations for UMC authors.
* Ensure deprecation messages remain credible by tying them to actual removal.

== Deprecation Lifecycle ==
=== Marking Deprecated ===
* When an API or feature is obsolete, mark it deprecated immediately.
* Deprecation message must include: version deprecated, recommended replacement, and planned removal version.

=== Minimum Deprecation Period ===
* Deprecated features remain for one stable release cycle.
* During this period, warnings are shown with migration guidance.

=== Sunset Clause ===
* After one stable release, the feature is scheduled for removal in the next release.
* No indefinite wrappers. “Deprecated” always means “will be removed.”

=== Removal ===
* Features are removed as scheduled, even if some UMCs still rely on them.
* Routine cleanup is a valid reason for removal — no need to wait for a blocking obstacle.

== Support for UMC Authors ==
* '''Migration Tools:''' wmllint/wmlscope must be updated to suggest or apply fixes automatically.
* '''Documentation:''' Wiki entries must clearly list deprecated features, replacements, and removal timelines.
* '''Major Versions:''' For large‑scale removals, major version bumps (e.g., 2.0) provide a clean slate.

== Enforcement ==
* Deprecation without removal is not allowed.
* Consensus is required to '''delay''' removal, not to perform it.
* Developers are empowered to perform routine cleanup without prolonged debate.

== Refuting Common Objections ==
* '''“Deprecation messages are helpful.”'''
** True, but only if they are credible. If removal never happens, the message is misleading.
** Warnings that never resolve train UMC authors to ignore them, undermining trust in tools.
** Messages stay helpful only when backed by action: clear timelines and actual removal.

* '''“Wrappers are harmless.”'''
** Wrappers accumulate and clutter the codebase, making it harder to maintain.
** They give a false sense of safety while delaying modernization.
** Routine cleanup prevents technical debt from piling up.

* '''“UMC authors need stability.”'''
** Stability comes from predictability, not indefinite legacy.
** Clear removal timelines and migration tools give authors confidence.
** Indefinite deprecation leaves authors in limbo, forcing piecemeal porting anyway.

== Summary ==
This policy makes deprecation meaningful. UMC authors get clear timelines and migration guidance, while developers can keep the codebase lean. Wrappers and indefinite deprecation are eliminated, ensuring that “deprecated” is a real lifecycle stage rather than a cosmetic label.

User:Bssarkar

2026-04-11T11:38:04Z

Bssarkar: new deprecation policy

= Revised Deprecation Policy =

== Goals ==
* Keep the codebase clean and maintainable.
* Provide clear expectations for UMC authors.
* Ensure deprecation messages remain credible by tying them to actual removal.

== Deprecation Lifecycle ==
# '''Marking Deprecated'''
* When an API or feature is obsolete, mark it deprecated immediately.
* Deprecation message must include: version deprecated, recommended replacement, and planned removal version.

# '''Minimum Deprecation Period'''
* Deprecated features remain for one stable release cycle.
* During this period, warnings are shown with migration guidance.

# '''Sunset Clause'''
* After one stable release, the feature is scheduled for removal in the next release.
* No indefinite wrappers. “Deprecated” always means “will be removed.”

# '''Removal'''
* Features are removed as scheduled, even if some UMCs still rely on them.
* Routine cleanup is a valid reason for removal — no need to wait for a blocking obstacle.

== Support for UMC Authors ==
* '''Migration Tools:''' wmllint/wmlscope must be updated to suggest or apply fixes automatically.
* '''Documentation:''' Wiki entries must clearly list deprecated features, replacements, and removal timelines.
* '''Major Versions:''' For large‑scale removals, major version bumps (e.g., 2.0) provide a clean slate.

== Enforcement ==
* Deprecation without removal is not allowed.
* Consensus is required to '''delay''' removal, not to perform it.
* Developers are empowered to perform routine cleanup without prolonged debate.

== Refuting Common Objections ==
* '''“Deprecation messages are helpful.”'''
– True, but only if they are credible. If removal never happens, the message is misleading.
– Warnings that never resolve train UMC authors to ignore them, undermining trust in tools.
– Messages stay helpful only when backed by action: clear timelines and actual removal.

* '''“Wrappers are harmless.”'''
– Wrappers accumulate and clutter the codebase, making it harder to maintain.
– They give a false sense of safety while delaying modernization.
– Routine cleanup prevents technical debt from piling up.

* '''“UMC authors need stability.”'''
– Stability comes from predictability, not indefinite legacy.
– Clear removal timelines and migration tools give authors confidence.
– Indefinite deprecation leaves authors in limbo, forcing piecemeal porting anyway.

== Summary ==
This policy makes deprecation meaningful. UMC authors get clear timelines and migration guidance, while developers can keep the codebase lean. Wrappers and indefinite deprecation are eliminated, ensuring that “deprecated” is a real lifecycle stage rather than a cosmetic label.

PreprocessorRef

2026-04-07T14:14:32Z

Bssarkar: /* Macro inclusions */ mention that space inside "" is preserved

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However, the '''WML preprocessor''' allows the inclusion of more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [https://www.wesnoth.org/macro-reference.html the macro reference] for the list of predefined core macros.

Macros have scoping rules such that addons have separate preprocessing contexts, meaning that they can be overridden however an author of UMC wishes to override them, without worrying about breaking other add-ons.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. <code>#define-#enddef</code> blocks cannot be nested inside another <code>#define</code>, as of Wesnoth 1.19.

As an example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation|WML Optimisation]].

==== Whitespace in Macros ====

When expanding a macro, '''''all''''' whitespace in the definition of the macro is preserved. The <tt>#arg</tt> declarations for optional arguments are removed including the final newline. The body of the optional argument (the default value) is similarly processed just as if it were a macro, so all whitespace is preserved.

There are two main practical implications of these rules:

* When using a macro to define simple constants to be used inline in the middle of an attribute value, the entire content and the <tt>#enddef</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_CONSTANT
42#enddef</syntaxhighlight>
* If using a macro inside a quoted string, you should not indent the contents of the macro, as the indentation will be preserved upon macro substitution.
* Similarly if you use an optional argument in the middle of an attribute value, the entire content and the <tt>#endarg</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_MACRO
#arg OPTIONAL_ARG
default#endarg
key = "composite {OPTIONAL_ARG} value"
#enddef</syntaxhighlight>

=== #arg ===

{{DevFeature1.13|7}}

'''Syntax: #arg ''symbol'' ''<newline>'' ''default value'' #endarg'''

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

For a multiline optional argument defined and called as follows:
<syntaxhighlight lang="wml">
#define MY_MACRO
#arg MULTILINE
[some_tag]
some_attribute = "some value"
[/some_tag]
#endarg
...
#enddef

{MY_MACRO (MULTILINE=[other_tag]
other_attribute = "other value"
[/other_tag])}
</syntaxhighlight>

'''Note:''' As with #enddef, the final line break before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a line break in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''. Wesnoth expects this to be done when overriding an existing macro, and will warn you if you redefine an existing macro without an explicit #undef before it.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. If they are already quoted, space inside quotes will be preserved even without parentheses. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

This way even complex arguments can be passed:

<syntaxhighlight lang="wml">
{MODIFY_UNIT (
[filter_adjacent]
canrecruit=yes
[/filter_adjacent]
) side 2}
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-defined''. If not, it will be replaced by ''substitution-if-not-defined'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-defined'' [#else ''substitution-if-defined''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as [[#Inclusion_directive_.7B.7D|include directives]].

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

=== #deprecated ===

{{DevFeature1.13|11}}

'''Syntax:''' '''#deprecated 1 [''message'']'''

'''Syntax:''' '''#deprecated 2 ''version'' [''message'']'''

'''Syntax:''' '''#deprecated 3 ''version'' [''message'']'''

'''Syntax:''' '''#deprecated 4 [''message'']'''

The first argument is the deprecation level, while ''version'' is the Wesnoth version where this deprecated file/macro is supposed to be removed. ''message'' is the optional deprecation message. The recommended usage is to provide ''message''.

The effect of this directive depends on whether it appears within a macro definition.

* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.

Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)

If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

Note that except during an actual game, '''MULTIPLAYER''', '''EDITOR''' and previous campaign defines, are not guaranteed to be undefined, especially when coming back to the titlescreen. So it is not enough to hide contents inside of an #ifdef to prevent them from being seen by the campaign selection dialog, for example for multiplayer specific '''[campaign]'''s or '''[modification]'''s '''type=mp''' must be used.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line). Can also be set by typing <code>:</code> to bring up [[CommandMode]], then typing <code>debug</code>, and then restarting the scenario.
* '''APPLE''': defined while processing the main game data when running on Mac OS X. This primarily exists to switch Control for Command in hotkeys, which is why there are no defines for other platforms.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.
* '''CURRENT_FILE''': Expands to the name of the current WML file.
* '''CURRENT_DIRECTORY''': Expands to the preprocessor path of the parent directory for the current WML file (e.g. for <code><user data dir>/data/add-ons/My_Addon/_main.cfg</code> this evaluates to <code>~add-ons/My_Addon</code>).
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.
* '''SCHEMA_VALIDATION''': defined if the validator is being run.
* '''__WMLUNITS__''': defined when the tool to create [https://units.wesnoth.org units.wesnoth.org] is being run.

A ''very large'' number of additional macros are provided as part of the default game core WML. For a full list of those, check the [https://www.wesnoth.org/macro-reference.html macro reference].

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will first preprocess '''data/core/macros''' and '''data/core/terrain-graphics''', and afterwards the specified path. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulting preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the current directory.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
-p data/gui/macros/_initial.cfg /tmp --preprocess-output-macros=macros
-p myfile.cfg ~/result --preprocess-input-macros=/tmp/macros

When it starts getting complicated, such as a file that depends on multiple other files, it is probably easiest to simply "include" the dependencies:

* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
Add {gui/macros/_initial.cfg} to the beginning of myfile.cfg
-p myfile.cfg ~/result

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]] (explains relationship between comments and preprocessor directives)
* [[ReferenceWML]]

[[Category: WML Reference]]

PreprocessorRef

2026-04-04T05:52:41Z

Bssarkar: /* #deprecated */ version is actually mandatory for deprecation levels 2/3

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However, the '''WML preprocessor''' allows the inclusion of more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [https://www.wesnoth.org/macro-reference.html the macro reference] for the list of predefined core macros.

Macros have scoping rules such that addons have separate preprocessing contexts, meaning that they can be overridden however an author of UMC wishes to override them, without worrying about breaking other add-ons.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. <code>#define-#enddef</code> blocks cannot be nested inside another <code>#define</code>, as of Wesnoth 1.19.

As an example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation|WML Optimisation]].

==== Whitespace in Macros ====

When expanding a macro, '''''all''''' whitespace in the definition of the macro is preserved. The <tt>#arg</tt> declarations for optional arguments are removed including the final newline. The body of the optional argument (the default value) is similarly processed just as if it were a macro, so all whitespace is preserved.

There are two main practical implications of these rules:

* When using a macro to define simple constants to be used inline in the middle of an attribute value, the entire content and the <tt>#enddef</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_CONSTANT
42#enddef</syntaxhighlight>
* If using a macro inside a quoted string, you should not indent the contents of the macro, as the indentation will be preserved upon macro substitution.
* Similarly if you use an optional argument in the middle of an attribute value, the entire content and the <tt>#endarg</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_MACRO
#arg OPTIONAL_ARG
default#endarg
key = "composite {OPTIONAL_ARG} value"
#enddef</syntaxhighlight>

=== #arg ===

{{DevFeature1.13|7}}

'''Syntax: #arg ''symbol'' ''<newline>'' ''default value'' #endarg'''

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

For a multiline optional argument defined and called as follows:
<syntaxhighlight lang="wml">
#define MY_MACRO
#arg MULTILINE
[some_tag]
some_attribute = "some value"
[/some_tag]
#endarg
...
#enddef

{MY_MACRO (MULTILINE=[other_tag]
other_attribute = "other value"
[/other_tag])}
</syntaxhighlight>

'''Note:''' As with #enddef, the final line break before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a line break in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''. Wesnoth expects this to be done when overriding an existing macro, and will warn you if you redefine an existing macro without an explicit #undef before it.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

This way even complex arguments can be passed:

<syntaxhighlight lang="wml">
{MODIFY_UNIT (
[filter_adjacent]
canrecruit=yes
[/filter_adjacent]
) side 2}
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-defined''. If not, it will be replaced by ''substitution-if-not-defined'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-defined'' [#else ''substitution-if-defined''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as [[#Inclusion_directive_.7B.7D|include directives]].

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

=== #deprecated ===

{{DevFeature1.13|11}}

'''Syntax:''' '''#deprecated 1 [''message'']'''

'''Syntax:''' '''#deprecated 2 ''version'' [''message'']'''

'''Syntax:''' '''#deprecated 3 ''version'' [''message'']'''

'''Syntax:''' '''#deprecated 4 [''message'']'''

The first argument is the deprecation level, while ''version'' is the Wesnoth version where this deprecated file/macro is supposed to be removed. ''message'' is the optional deprecation message. The recommended usage is to provide ''message''.

The effect of this directive depends on whether it appears within a macro definition.

* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.

Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)

If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

Note that except during an actual game, '''MULTIPLAYER''', '''EDITOR''' and previous campaign defines, are not guaranteed to be undefined, especially when coming back to the titlescreen. So it is not enough to hide contents inside of an #ifdef to prevent them from being seen by the campaign selection dialog, for example for multiplayer specific '''[campaign]'''s or '''[modification]'''s '''type=mp''' must be used.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line). Can also be set by typing <code>:</code> to bring up [[CommandMode]], then typing <code>debug</code>, and then restarting the scenario.
* '''APPLE''': defined while processing the main game data when running on Mac OS X. This primarily exists to switch Control for Command in hotkeys, which is why there are no defines for other platforms.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.
* '''CURRENT_FILE''': Expands to the name of the current WML file.
* '''CURRENT_DIRECTORY''': Expands to the preprocessor path of the parent directory for the current WML file (e.g. for <code><user data dir>/data/add-ons/My_Addon/_main.cfg</code> this evaluates to <code>~add-ons/My_Addon</code>).
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.
* '''SCHEMA_VALIDATION''': defined if the validator is being run.
* '''__WMLUNITS__''': defined when the tool to create [https://units.wesnoth.org units.wesnoth.org] is being run.

A ''very large'' number of additional macros are provided as part of the default game core WML. For a full list of those, check the [https://www.wesnoth.org/macro-reference.html macro reference].

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will first preprocess '''data/core/macros''' and '''data/core/terrain-graphics''', and afterwards the specified path. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulting preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the current directory.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
-p data/gui/macros/_initial.cfg /tmp --preprocess-output-macros=macros
-p myfile.cfg ~/result --preprocess-input-macros=/tmp/macros

When it starts getting complicated, such as a file that depends on multiple other files, it is probably easiest to simply "include" the dependencies:

* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
Add {gui/macros/_initial.cfg} to the beginning of myfile.cfg
-p myfile.cfg ~/result

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]] (explains relationship between comments and preprocessor directives)
* [[ReferenceWML]]

[[Category: WML Reference]]

Android

2026-04-04T03:12:34Z

Bssarkar: /* Playing controls */ mention reachmap not vanishing

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it. (After deselection, the reachmap won't vanish, but it was deselected, so if you touch another unit the reachmap will change.)
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.
* Long press on any hex to show the Right-click context menu that has Recruit/Recall etc.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

== Dev Notes ==
=== Package manifest (manifest.txt) and download status file (status.properties) ===
{{DevFeature1.19|19}}

The package manifest file (<code>manifest.txt</code>) is a file on the Wesnoth sourceforge site that the Android Wesnoth client reads to figure out available packages for download. For example, for Wesnoth 1.19.19 it is located here: [https://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.19.19/android-data/manifest.txt/download manifest.txt]. This path is mostly hardcoded [https://github.com/wesnoth/wesnoth/blob/ff3ad482074d2698762cffcad08660c77ea1bb2c/packaging/android/app/src/main/java/org/wesnoth/Wesnoth/InitActivity.java#L66-L67 here] with only the version code part changing per release.

The <code>status.properties</code> file is generated by the Android client to track details of downloaded packages, and is created inside <code>/sdcard/Android/data/org.wesnoth.Wesnoth/files/gamedata</code>.

=== Version Code scheme (1191601001 - post 1.19.16 fixup) ===
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

=== New Version Code scheme draft ===
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

=== Other version code scheme drafts ===

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

==== <code>MMMPPpxxVA</code> ====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - Build variant (0 is clean, 1 might be google play integrations. Could be a bitfield or an enum)
* A - ABI (as above)
* x - Unspecified, available for expanding these fields or adding other flags

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, default (clean) variant, arm64

==== <code>12MMMPPpVA</code> ====
Basically the same thing, just shifted to the right by eating up the unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 clean arm64, as above.

==== <code>12MMPPpxVA</code> ====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 clean arm64, as above.

PreprocessorRef

2026-03-29T16:36:11Z

Bssarkar: /* #deprecated */ Add more explanation about #deprecated arguments, and mention optionality

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However, the '''WML preprocessor''' allows the inclusion of more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [https://www.wesnoth.org/macro-reference.html the macro reference] for the list of predefined core macros.

Macros have scoping rules such that addons have separate preprocessing contexts, meaning that they can be overridden however an author of UMC wishes to override them, without worrying about breaking other add-ons.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. <code>#define-#enddef</code> blocks cannot be nested inside another <code>#define</code>, as of Wesnoth 1.19.

As an example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation|WML Optimisation]].

==== Whitespace in Macros ====

When expanding a macro, '''''all''''' whitespace in the definition of the macro is preserved. The <tt>#arg</tt> declarations for optional arguments are removed including the final newline. The body of the optional argument (the default value) is similarly processed just as if it were a macro, so all whitespace is preserved.

There are two main practical implications of these rules:

* When using a macro to define simple constants to be used inline in the middle of an attribute value, the entire content and the <tt>#enddef</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_CONSTANT
42#enddef</syntaxhighlight>
* If using a macro inside a quoted string, you should not indent the contents of the macro, as the indentation will be preserved upon macro substitution.
* Similarly if you use an optional argument in the middle of an attribute value, the entire content and the <tt>#endarg</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_MACRO
#arg OPTIONAL_ARG
default#endarg
key = "composite {OPTIONAL_ARG} value"
#enddef</syntaxhighlight>

=== #arg ===

{{DevFeature1.13|7}}

'''Syntax: #arg ''symbol'' ''<newline>'' ''default value'' #endarg'''

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

For a multiline optional argument defined and called as follows:
<syntaxhighlight lang="wml">
#define MY_MACRO
#arg MULTILINE
[some_tag]
some_attribute = "some value"
[/some_tag]
#endarg
...
#enddef

{MY_MACRO (MULTILINE=[other_tag]
other_attribute = "other value"
[/other_tag])}
</syntaxhighlight>

'''Note:''' As with #enddef, the final line break before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a line break in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''. Wesnoth expects this to be done when overriding an existing macro, and will warn you if you redefine an existing macro without an explicit #undef before it.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

This way even complex arguments can be passed:

<syntaxhighlight lang="wml">
{MODIFY_UNIT (
[filter_adjacent]
canrecruit=yes
[/filter_adjacent]
) side 2}
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-defined''. If not, it will be replaced by ''substitution-if-not-defined'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-defined'' [#else ''substitution-if-defined''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as [[#Inclusion_directive_.7B.7D|include directives]].

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

=== #deprecated ===

{{DevFeature1.13|11}}

'''Syntax:''' '''#deprecated 1 [''message'']'''

'''Syntax:''' '''#deprecated 2 [''version'' ''message'']'''

'''Syntax:''' '''#deprecated 3 [''version'' ''message'']'''

'''Syntax:''' '''#deprecated 4 [''message'']'''

The first argument is the deprecation level, while ''message'' is the optional deprecation message, and ''version'' is the optional Wesnoth version where this deprecated file/macro is supposed to be removed. (Although optional, the recommended usage is to provide ''message'' and ''version''.)

The effect of this directive depends on whether it appears within a macro definition.

* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.

Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)

If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

Note that except during an actual game, '''MULTIPLAYER''', '''EDITOR''' and previous campaign defines, are not guaranteed to be undefined, especially when coming back to the titlescreen. So it is not enough to hide contents inside of an #ifdef to prevent them from being seen by the campaign selection dialog, for example for multiplayer specific '''[campaign]'''s or '''[modification]'''s '''type=mp''' must be used.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line). Can also be set by typing <code>:</code> to bring up [[CommandMode]], then typing <code>debug</code>, and then restarting the scenario.
* '''APPLE''': defined while processing the main game data when running on Mac OS X. This primarily exists to switch Control for Command in hotkeys, which is why there are no defines for other platforms.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.
* '''CURRENT_FILE''': Expands to the name of the current WML file.
* '''CURRENT_DIRECTORY''': Expands to the preprocessor path of the parent directory for the current WML file (e.g. for <code><user data dir>/data/add-ons/My_Addon/_main.cfg</code> this evaluates to <code>~add-ons/My_Addon</code>).
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.
* '''SCHEMA_VALIDATION''': defined if the validator is being run.
* '''__WMLUNITS__''': defined when the tool to create [https://units.wesnoth.org units.wesnoth.org] is being run.

A ''very large'' number of additional macros are provided as part of the default game core WML. For a full list of those, check the [https://www.wesnoth.org/macro-reference.html macro reference].

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will first preprocess '''data/core/macros''' and '''data/core/terrain-graphics''', and afterwards the specified path. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulting preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the current directory.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
-p data/gui/macros/_initial.cfg /tmp --preprocess-output-macros=macros
-p myfile.cfg ~/result --preprocess-input-macros=/tmp/macros

When it starts getting complicated, such as a file that depends on multiple other files, it is probably easiest to simply "include" the dependencies:

* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
Add {gui/macros/_initial.cfg} to the beginning of myfile.cfg
-p myfile.cfg ~/result

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]] (explains relationship between comments and preprocessor directives)
* [[ReferenceWML]]

[[Category: WML Reference]]

Maintenance tools

2026-03-24T11:14:32Z

Bssarkar: /* wmllint */ Explain no-icon flag based on code

<div class="floatright"> __TOC__ </div>

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These
are:

; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.

; wmllint: a utility for sanity-checking WML syntax and porting your old WML to the current version of WML.

; wmlindent: a utility for reindenting WML to a uniform style.

; GUI.pyw: a graphical interface

== General Information ==

You will need a Python 3 interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python 3 installed; for Windows it's a free download
from http://www.python.org. You will also need to know how to run command-line tools on your system.

If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.16-tools (or the convenient version).
sudo apt install wesnoth-1.16-tools

All three tools will require you to supply a <i>directory list</i>. This is a set of directories containing the WML files you want to work on.

This page is intended as documentation for users.

<u>Note to Windows Users:</u> This means you have to run it from the '''Command Line'''. The command line may be reached by hitting Start, then Run, then "cmd" or "command" depending on your version of Windows.

Example uses:
python wmllint path\to\files
python wmlindent path\to\files

Another example:
"C:\Program Files\Python3.7\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns
(You have to specify the full directory path to the executable if you don't have your environment variables set up correctly).
The first thing you type is the path to your python executable, followed by a space. The second thing you type is the path to the desired script to run, followed by a space. The third thing you type is the path to the folder (or file) to be processed.

'''A convenient way of running wmllint''' on Linux (Debian or Ubuntu) and Windows in comparison, '''Linux''':

Assuming we're working with wesnoth 1.16 or more advanced versions.
python3 /usr/share/games/wesnoth/1.16/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.16/data/core ~/.local/share/wesnoth/1.16/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
I have these commands inside of a file named
wmllint_dryrun_ASC.sh
and execute it by opening a shell (=terminal, console, command window, bash,...), navigating into the directory with that file and typing
bash wmllint_dryrun_ASC.sh
The python3 command should be automatically known on Debian. The path to the script tells the python interpreter what to execute. --dryrun: A wmllint option, see below. The path to the core files is needed to let wmllint know about e.g. defined core units, followed by the path to the add-on that shall be checked; the last two commands cause the result of the wmllint usage to be written into those files in the same directory as the script.
'''Windows''', this is logically exactly the same as the Linux shell script above, so if you are on a Mac you can probably conclude how you need to adapt the paths:
E:\Python37\python.exe E:\Programme\Wesnoth_1.16_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.16_git\data\core E:\Programme\Wesnoth_1.16_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
This is the content of a .txt file, whose extension I rename to .bat and double-click onto it. Opening a command window is not needed this way.
Since Python isn't natively installed on windows and I don't have environment variables set, the full path to python.exe is given. If your directories contain spaces it may help to include the path in quotes:
"C:\Programs\Battle for Wesnoth 1.16\data\tools\wmllint"
Remember that you do not need to enter all of the commands/paths at once. If it doesn't work, start with only "python" or "C:\Python37\python.exe" or the like and interpret the error messages that you get. If you get an "unknown command", python isn't installed or environment variables aren't set correctly. After that, you can add the later commands one by one.

== wmlscope ==

The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic (see [https://github.com/wesnoth/wesnoth/issues/5332 issue 5332] for more info). They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.

<tt>wmlscope</tt> also checks macro invocations for consistency. It will complain
if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

<table class="wikitable"><tr>
<th>Type</th>
<th>Meaning</th>
<th>Formals requiring this type</th>
<th>Literals of this type</th>
</tr>
<tr>
<td>side</td>
<td>a single side number</td>
<td>SIDE, *_SIDE, SIDE[0-9]</td>
<td>a numeric or "global"</td>
</tr>
<tr>
<td>numeric</td>
<td>a numeric integer literal</td>
<td>SIDE, X, Y, RED, GREEN, BLUE, TURN, PROB, LAYER, TIME, *_SIDE, *NUMBER, *AMOUNT, *COST, *RADIUS, *_X, *_Y, *_INCREMENT, *_FACTOR, *_TIME, *_SIZE, DURATION</td>
<td>\-?[0-9]+</td>
</tr>
<tr>
<td>percentage</td>
<td>a percentage</td>
<td>*PERCENTAGE</td>
<td>a numeric or 0\.[0-9]+</td>
</tr>
<tr>
<td>position</td>
<td>a single x,y coordinate</td>
<td>POSITION, *_POSITION, BASE</td>
<td>-?[0-9]+,-?[0-9]+</td>
</tr>
<tr>
<td>span</td>
<td>a set of coordinates or coordinate ranges</td>
<td>*_SPAN</td>
<td>a numeric, position or ([0-9]+\-[0-9]+,?|[0-9]+,?)+</td>
</tr>
<tr>
<td>alliance</td>
<td>a set of side numbers</td>
<td>SIDES, *_SIDES</td>
<td>a span, or the empty string</td>
</tr>
<tr>
<td>range</td>
<td>an attack range</td>
<td>RANGE</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>alignment</td>
<td>an alignment keyword</td>
<td>ALIGN</td>
<td>"lawful" or "neutral" or "chaotic"</td>
</tr>
<tr>
<td>types</td>
<td>a set of unit types</td>
<td>TYPES</td>
<td>a shortname, name, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>terrain_pattern</td>
<td>a set of terrain codes to filter</td>
<td>ADJACENT*, TERRAINLIST*, *TERRAIN_PATTERN, RESTRICTING</td>
<td>a terrain_code or name</td>
</tr>
<tr>
<td>terrain_code</td>
<td>a single terrain code, perhaps with overlay</td>
<td>TERRAIN*, *TERRAIN</td>
<td>a shortname or (\*|[A-Z][a-z]+)\^([A-Z][a-z\\|/]+\Z)?</td>
</tr>
<tr>
<td>shortname</td>
<td>a terrain code or a short, capitalized variable name</td>
<td></td>
<td>[A-Z][a-z][a-z]?</td>
<tr>
<td>name</td>
<td>a name or identifier</td>
<td>NAME, VAR, IMAGESTEM, ID, FLAG, *_NAME, *_ID, NAMESPACE, BUILDER, *_VAR</td>
<td>anything without spaces that matches no other type</td>
</tr>
<tr>
<td>optional_string</td>
<td>a string value (may be empty)</td>
<td>ID_STRING, NAME_STRING, DESCRIPTION, IPF</td>
<td>a string, or the empty string</td>
</tr>
<tr>
<td>string</td>
<td>a nonempty string not matching any of the preceding types</td>
<td>STRING, TYPE, TEXT, *_STRING, *_TYPE, *_TEXT</td>
<td>a shortname, a name, a stringliteral, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>stringliteral</td>
<td>a string in doublequotes or a translated string</td>
<td></td>
<td>".*" or _.* but not _[a-z].*</td>
</tr>
<tr>
<td>image</td>
<td>an image path, perhaps with [[ImagePathFunctionWML|image path functions]]</td>
<td>*IMAGE, PROFILE</td>
<td>[A-Za-z0-9{}.][A-Za-z0-9_/+{}.-]*\.(png|jpg)(?=(~.*)?)</td>
</tr>
<tr>
<td>sound</td>
<td>a music or sound filename</td>
<td>MUSIC, SOUND</td>
<td>string ending with ".wav" or ".ogg"</td>
</tr>
<tr>
<td>filter</td>
<td>[[FilterWML|WML filter]]</td>
<td>FILTER</td>
<td>any non-quoted string containing "="</td>
</tr>
<tr>
<td>WML</td>
<td>arbitrary WML fragment</td>
<td>WML, *_WML</td>
<td>any non-quoted string containing "=", or the empty string</td>
</tr>
<tr>
<td>affix</td>
<td>a prefix, suffix, or infix for a variable name</td>
<td>AFFIX, *AFFIX, POSTFIX, ROTATION</td>
<td>a shortname or name, or the empty string</td>
</tr>
<tr>
<td>any</td>
<td>anything</td>
<td>*VALUE, [ARS][0-9]</td>
<td>anything</td>
</tr>
</table>

If the actual argument is a macro call {.*}, then it matches any formal. Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in <i>data/tools/Makefile</i> of the source distribution. Here are some of those reports:

; make unresolved: Report on unresolved macro calls and resource references; also report macro argument-type mismatches. (This is what you are most likely to want to do).

; make all: Report all macro and resource file references, not just unresolved ones.

; make collisions: Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand
[http://docs.python.org/lib/re-syntax.html Python regular expressions].

; -h, --help: Emit a help message and quit
; -c, --crossreference: Report resolved macro references (implies <tt>-w 1</tt>)
; -C, --collisions: Report duplicate resource files
; -d, --deflist: Make definition list. (This one is for campaign server maintainers.)
; -e <i>regexp</i>, --exclude <i>regexp</i>: Ignore files matching the specified regular expression.
; -f <i>dir</i>, --from <i>dir</i>: Report only on macros defined under <i>dir</i>
; -l, --listfiles: List files that will be processed
; -r <i>ddd</i>, --refcount=<i>ddd</i>: Report only on macros with references in exactly <i>ddd</i> files.
; -t <i>TYPELIST</i>, --typelist <i>TYPELIST</i>: List actual & formal argtypes for calls in fname
; -u, --unresolved: Report unresolved macro references
; -w, --warnlevel: Set to 1 to warn of duplicate macro definitions
; -p, --progress: Show progress
; --force-used reg: Ignore reference count 0 on names matching regexp
; --extracthelp: Extract help from macro definition comments.
; --unchecked: Report all macros with untyped formals.
; --version: show program's version number and exit

These options are used with a list of directories as arguments; if none is given,
<tt>wmlscope</tt> behaves as though the current directory had been specified as a
single argument. Each directory is treated as a separate domain for
macro and resource visibility purposes.

<tt>wmlscope</tt> recognizes two kinds of namespace, exporting and non-exporting.
Exporting namespaces make all their resources and macro names
globally visible. You can make a namespace exporting by embedding
a comment like this in it:

# wmlscope: export=yes

Wesnoth core data is an exporting namespace. Campaigns are non-exporting;
they should contain the declaration

# wmlscope: export=no

somewhere. <tt>wmlscope</tt> will complain when it sees a namespace with no export
property, then treat it as non-exporting.

You can tell <tt>wmlscope</tt> to ignore stretches of config files
with the following magic comments:

# wmlscope: start ignoring
# wmlscope: stop ignoring

Similarly, you can tell <tt>wmlscope</tt> to ignore multiple or duplicate macro
definitions in a range of lines with the following magic comments:

# wmlscope: start conditionals
# wmlscope: stop conditionals

The following magic comment:

# wmlscope: prune FOOBAR

will cause <tt>wmlscope</tt> to forget about all but one of the definitions of
<tt>FOOBAR</tt> it has seen. This will be useful mainly for symbols that have
different definitions enabled by an <tt>#ifdef</tt>.

Due to a preprocessor limitation, inline macros cannot contain a documentation
string. If you need to document these macros in the HTML macro reference, you
can use the following directive:

# wmlscope: docstring FOOBAR

The docstring for the FOOBAR macro will be collected until a non-comment line,
a <tt>#define</tt> or another <tt># wmlscope: docstring</tt> are found. External
docstrings '''''must''''' be defined before the macro to which they refer; defining
two or more external docstrings keeps only the most recent one, but having both an
external and an internal docstring is allowed (in this case, the internal one
will be appended to the external one in the macro reference).

This tool does catch one kind of implicit reference: if an attack name
is specified but no icon is given, the attack icon will default to
a name generated from the attack name. This behavior can be suppressed
by adding a magic comment containing the string "no-icon" to the <tt>name=</tt>
line.

The checking done by this tool has a couple of flaws:

(1) It doesn't actually evaluate file inclusions. Instead, any
macro definition satisfies any macro call made under the same
directory. Exception: when an <tt>#undef</tt> is detected, the macro is
tagged local and not visible outside the span of lines where it was
defined.

(2) It doesn't read <tt>[binary_path]</tt> tags, as this would require
implementing a WML parser. Instead, it assumes that a resource-file
reference can be satisfied by any matching image file from anywhere
in the same directory it came from. The resources under the '''''first'''''
directory argument (only) are visible everywhere.

(3) A reference with embedded {}s in a macro will have the macro's
formal args substituted in at WML evaluation time. Instead, this
tool treats each {} as a .* wildcard and considers the reference to
match '''''every''''' resource filename that matches that pattern.
Under appropriate circumstances this might report a resource filename
statically matching the pattern as having been referenced even
though none of the actual macro calls would actually generate it.

Problems (1) and (2) imply that this tool might conceivably report
that a reference has been satisfied when under actual
WML-interpreter rules it has not.

The reporting format is compatible with GNU Emacs compile mode.

For debugging purposes, an in-line comment of the form

# wmlscope: warnlevel NNN

sets the warning level.

== wmllint ==

<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:

* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.

* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. If you port such old code, use <tt>wmllint-1.4</tt>, which is located in the same directory as <tt>wmllint</tt>. It will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

<tt>wmllint</tt> also performs various sanity-checking operations, reporting:

* unbalanced tags
* strings that need a translation mark and do not have them
* strings that have a translation mark and should not
* translatable strings containing macro references
* filter references by description= (id= in 1.5) not matched by an actual unit
* abilities or traits without matching special notes, or vice-versa
* consistency between recruit= and recruitment_pattern= instances
* double space after punctuation in translatable strings.
* unknown races or movement types in units

<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

; -h, --help: Emit a help message and quit.
; -c, --clean: Clean up -bak files.
; -D, --diffs: Display diffs between converted and unconverted files.
; -d, --dryrun: List changes (-v) but don't perform them.
; -r, --revert: Revert the conversion from the -bak files.
; -m, --missing: Warn about tags without side= keys now applying to all sides.
; -s, --stripcr: Convert DOS-style CR/LF to Unix-style LF.
; -v, --verbose: Set verbosity; more details below.
; -K, --known: Suppress check for unknown unit types, recruits, races, scenarios, etc.
; -S, --nospellcheck: Suppress spellchecking
; --version: show program's version number and exit

The verbosity option works like this:

; -v: lists changes.
; -v -v: warns of maps already converted.
; -v -v -v: names each file before it's processed.
; -v -v -v -v: shows verbose parse details (developers only).

The recommended procedure is this:

# Run it with --dryrun first to see what it will do.
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
# Eyeball the changes with the --diff option.
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
# Test the conversion.
# Use either --clean to remove the -bak files or --revert to undo the conversion.

Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings. It will work automatically with any of [https://github.com/AbiWord/enchant enchant]'s spellchecking backends (including aspell, myspell, ispell, applespell, hunspell, nuspell, and so on, depending on the version of enchant), provided you have the <tt>enchant.py</tt> Python library installed. Note that the spellchecking results can vary depending on which backend enchant decides to use.

wmllint supports a number of magic comments to customize its behaviour and avoid false positives. All magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. In the below explanations, a string of the form <code>[a|b]</code> means you may use either <code>a</code> or <code>b</code> at that location, while a string of the form <code><arg></code> indicates free text substitution.

* <code>ignore</code>: Disables checking of terrains and translation marks on the current line only.
* <code>noconvert</code>: Disables conversion of terrains and image/sound filenames on the current line only.
* <code>markcheck [on|off]</code>: Enables or disables translation mark checking from the current (next?) line onward.
* <code>no-icon</code>: If an attack has no description, without this wmllint adds a dummy description to the attack which is just the name of the attack. With this, this description insertion is suppressed.
* <code>recognize <name></code>: Indicates that the character with the given name exists even though a declaration (ie a <code>[unit]</code> or <code>[side]</code> tag) is not visible.
* <code>whofield <macro> <number></code>: Indicates that the specified macro declares a character whose name is given by the specified argument to the macro.
* <code>whofield clear <macro></code>: Removes the <code>whofield</code> definition for the specified macro.
* <code>who <macro> is <name> <name> ...</code>: Indicates that the specified macro declares one or more characters whose names are given as a space-separated list. This can also be used for macros that auto-recall a list of characters, some of which join later or may die at some point. If a definition for the macro already exists, then the specified names are appended to it. If a name is preceded by a double minus (<code>-- <name></code>) then it is removed from the definition.
* <code>unwho all|<name></code>: Removes the <code>who</code> definition for the specified macro, or all <code>who</code> definitions.
* <code>usage of "<unit>" is <class></code>: Declares the usage of the specified unit (the <code>usage=</code> key in the <code>[unit_type]</code> tag). Useful if you are using macros to generate several similar unit types.
* <code>usagetype <class></code>: Declares a valid usage type for units. <code>usagetypes</code> is also recognized, and a comma-separated list of usage types can be specified.
* <code>validate-[on|off]</code>: Enables or disables stack-based validation checks. Use when you have unbalanced tags in macros.
* <code>unbalanced-[on|off]</code>: Similar to above, the precise difference is unclear.
* <code>no translatables</code>: Suppresses warnings about a missing textdomain declaration in the current file. Make sure the file really does have no translatable strings!
* <code>display [on|off]</code>: Enable or disable warnings about newlines in messages.
* <code>notecheck [on|off]</code>: Enable or disable note consistency checks for unit descriptions.
* <code>deathcheck [on|off]</code>: Enable or disable the check for units speaking in their death events.
* <code>[general|directory|local] spellings <word> <word> ...</code>: Declares the specified space-separated list of words to be valid spellings in the specified context. The context <code>local</code> indicates the current file only, while <code>directory</code> means the current file and any siblings in the same directory or subdirectories. The <code>global</code> context indicates the spellings are valid anywhere.
* <code>no spellcheck</code>: Disables spell checking on the current line.
* <code>skip-side</code>: Indicates that there is a missing side declaration at this location that will be provided by a macro expansion.
* <code>match <string> with <notes_macro></code>: Indicates that uses of the specified string in a unit definition (usually a macro, including the curly braces) should be matched up with the specified special notes macro (which is also specified as the full macro with curly braces).
* <code>no ellipsecheck</code>: Disables checking of unit ellipses on the current line.

=== Explanations of <tt>wmllint</tt> diagnostics ===
Some <tt>wmllint</tt> diagnostics may require further explanation for UMC authors to understand; this section will be for providing such explanations, and descriptions of how to solve and/or silence them.

In these, <code>%s</code> will be replaced by a string. When the recommended solution also includes a <code>%s</code>, it's a suggestion to copy the string from the error message into your code.

* <code>nonstandard word-wrap style within message</code>: This message meant there was an unexpected newline character within a <code>[message]</code> tag. However, this check was removed in the 1.15.10 release. Pre-1.15.10, add-on developers could silence by putting a <code># wmllint: display on</code> comment before the string and a <code># wmllint: display off</code> comment after the string, however, post-1.15.10, this is no longer necessary.
* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>unknown speaker '%s' of [message]</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the speaker is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is SPEAKER</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>unknown '%s' referred to by id</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the unit is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is UNIT</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>%s has unknown advancements</code> (in cases where you'd think the advancement ''would'' be known): This means the unit has an advancement that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load mainline units for checking advancements. Note that it's also possible that you just made typo, too, so be sure to check your spelling. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>.description may need hand fixup</code>: This one comes from mucking around with the <code>.description</code> field of unit data manually in a hackish fashion. There isn't really much of a way to work around it, besides just the "don't do that" solution.
* <code>tag stack nonempty (%s) at end of file.</code>: This means that you have unbalanced tags somewhere in the file, e.g. an opener without a closer, or vice versa. This can often be seen when defining macros for unit abilities. A way to fix this warning is to wrap the section with unbalanced tags with a <code># wmllint: unbalanced-on</code> magic comment beforehand and a <code># wmllint: unbalanced-off</code> magic comment afterwards. As having unbalanced tags will also cause issues for other WML maintenance tools, such as <tt>wmlindent</tt> and <tt>wmlxgettext</tt>, you may also want to add separate magic comments for each of them (see their documentation for the form they take).
* <code>unit declaration without side attribute</code>: the default side for a unit declaration when left implicit is side 1. Specify your unit sides explicitly to solve this.
* <code>no %s units recruitable at difficulty %s</code> (even when there are such units recruitable): This diagnostic has to do with matching the <code>usage</code> key of units recruitable by an AI side with their <code>recruitment_pattern</code>. It means the unit has a usage that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can know which mainline units are recruitable. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown movement type</code> (even when you'd think that that movement type ''would'' actually be known): This means the unit has a movetype that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline movement types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown race</code> (even when you'd think that that race ''would'' actually be known): This means the unit has a race that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline races. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>derivation of %s from %s does not resolve</code> (even when you'd think it would): This means that a unit using the [[UnitTypeWML#Other_tags|[base_unit]]] tag specifies a unit ID in that tag that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the core units for its derivation checks. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>[advancefrom] needs to be manually updated to [modify_unit_type] and moved into the _main.cfg file</code>: This one is pretty self-explanatory: [[UnitTypeWML#Unit_Type|[advancefrom]]] was deprecated in [https://github.com/wesnoth/wesnoth/commit/3950f40f3f0483032bc70b3e57166bd355acd9fc commit 3950f40] due to [https://github.com/wesnoth/wesnoth/issues/3955 issue #3955], and in fact doesn't even work anymore (in 1.16) as per [https://github.com/wesnoth/wesnoth/issues/6204 issue #6204]. The main reason <tt>wmllint</tt> can't fix this automatically is because it could end up being too complicated for it to figure out which files to edit if there are multiple uses of <code>[advancefrom]</code>, and it also doesn't want to assume where to put the [[ModificationWML|[modify_unit_type]]] tag in <tt>_main.cfg</tt>.

== wmlindent ==

Call with no arguments to filter WML on standard input to reindented WML on
standard output. If arguments are specified, they are taken to be files to be
re-indented in place; a directory name causes reindenting on all WML
beneath it.

The indent unit is four spaces. Absence of an option to change this is
deliberate; the purpose of this tool is to ''prevent'' style wars, not encourage
them.

On non-empty lines, this code never modifies anything but leading and
trailing whitespace. Leading whitespace will be regularized to the
current indent; trailing whitespace will be stripped. After processing
all lines will end with a Unix-style <code>\n</code> end-of-line marker.

Runs of entirely blank lines will be reduced to one blank line, except
in two cases where they will be discarded: (a) before WML closing
tags, and (b) after WML opening tags.

It is possible to wrap a section of lines in special comments so that
<tt>wmlindent</tt> will ignore them. You may need to do this for unbalanced
macros (it's better, though, to get rid of those where possible).
Use '<code>wmlindent: {start,stop} ignoring</code>' anywhere in a comment.

It is also possible to declare custom openers an closers, e.g for macros
that are actually control constructs. To do this, use declarations

# wmlindent: opener "{EXCEPTIONAL_OPENER "
# wmlindent: closer "{EXCEPTIONAL_CLOSER "

The lines after an opener will be indented an extra level; a closer
and lines following will be indented one level less. Note that these
declare prefixes; any prefix match to the non-whitespace text of a line
will be recognized.

The public utility macros "<code>{FOREACH</code>" and "<code>{NEXT</code>" come as wired-in exceptions,
because it is not guaranteed that their indent declarations will be processed
before the macro library is reached.

Interrupting <tt>wmlindent</tt> ought to be safe, as each reindenting will be done to a copy
that is atomically renamed when it's done. If the output file is identical
to the input, the output file will simply be deleted, so the timestamp
on the input file won't be touched.

The <tt>--dryrun</tt> option detects and reports files that would be changed
without changing them. The <tt>--verbose</tt> or <tt>-v</tt> option enables reporting
of files that are (or would be, under <tt>--dryrun</tt>) changed. With <tt>-v -v</tt>,
unchanged files are also reported. The <tt>--exclude</tt> option takes a regexp
and excludes files matching it.

If you don't apply this tool to your own WML that you wish to submit, the
mainline-campaign maintainers will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML
that is syntactically unbalanced. Unbalanced double quotes that aren't part
of a multiline literal will also confuse it. You will receive warnings
if there's an indent open at end of file or if a closer occurs with
indent already zero; these two conditions strongly suggest unbalanced WML.

== GUI.pyw ==

Starting from version 1.11.15 and 1.13.0, a GUI (written in Tkinter, plus the themed widgets ttk) is available in the same directory as the other tools. To use it, you need to have a version of Python equal to or greater than 3.1.0 (the 3.0.x series doesn't include the ttk widgets, and as such is unsuitable for this script).

If you're on Linux, be sure to have installed the ''python3-tk'' module, '''or the application won't run at all'''. To install it in a Debian-based distro (like Ubuntu), type this line in a Terminal:
sudo apt install python3-tk

To start it, just double click on the GUI.pyw file. The interface is pretty much self-explanatory, and allows you to run wmllint, wmlscope, wmlindent and wmlxgettext, modify their options, select an add-on and save the tools' output as a text file.

== See Also ==
* [[Translation Maintenance Commands]] (for <tt>wmlxgettext</tt>)

[[Category:Create]]
[[Category:Tools]]

PreprocessorRef

2026-03-20T15:50:21Z

Bssarkar: /* #define */ Mention define/enddef non-nesting requirement (cf. GNA #21343)

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However, the '''WML preprocessor''' allows the inclusion of more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [https://www.wesnoth.org/macro-reference.html the macro reference] for the list of predefined core macros.

Macros have scoping rules such that addons have separate preprocessing contexts, meaning that they can be overridden however an author of UMC wishes to override them, without worrying about breaking other add-ons.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. <code>#define-#enddef</code> blocks cannot be nested inside another <code>#define</code>, as of Wesnoth 1.19.

As an example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation|WML Optimisation]].

==== Whitespace in Macros ====

When expanding a macro, '''''all''''' whitespace in the definition of the macro is preserved. The <tt>#arg</tt> declarations for optional arguments are removed including the final newline. The body of the optional argument (the default value) is similarly processed just as if it were a macro, so all whitespace is preserved.

There are two main practical implications of these rules:

* When using a macro to define simple constants to be used inline in the middle of an attribute value, the entire content and the <tt>#enddef</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_CONSTANT
42#enddef</syntaxhighlight>
* If using a macro inside a quoted string, you should not indent the contents of the macro, as the indentation will be preserved upon macro substitution.
* Similarly if you use an optional argument in the middle of an attribute value, the entire content and the <tt>#endarg</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_MACRO
#arg OPTIONAL_ARG
default#endarg
key = "composite {OPTIONAL_ARG} value"
#enddef</syntaxhighlight>

=== #arg ===

{{DevFeature1.13|7}}

'''Syntax: #arg ''symbol'' ''<newline>'' ''default value'' #endarg'''

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

For a multiline optional argument defined and called as follows:
<syntaxhighlight lang="wml">
#define MY_MACRO
#arg MULTILINE
[some_tag]
some_attribute = "some value"
[/some_tag]
#endarg
...
#enddef

{MY_MACRO (MULTILINE=[other_tag]
other_attribute = "other value"
[/other_tag])}
</syntaxhighlight>

'''Note:''' As with #enddef, the final line break before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a line break in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''. Wesnoth expects this to be done when overriding an existing macro, and will warn you if you redefine an existing macro without an explicit #undef before it.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

This way even complex arguments can be passed:

<syntaxhighlight lang="wml">
{MODIFY_UNIT (
[filter_adjacent]
canrecruit=yes
[/filter_adjacent]
) side 2}
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-defined''. If not, it will be replaced by ''substitution-if-not-defined'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-defined'' [#else ''substitution-if-defined''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as [[#Inclusion_directive_.7B.7D|include directives]].

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

=== #deprecated ===

{{DevFeature1.13|11}}

'''Syntax:''' '''#deprecated 1 ''message'''''

'''Syntax:''' '''#deprecated 2 ''version'' ''message'''''

'''Syntax:''' '''#deprecated 3 ''version'' ''message'''''

'''Syntax:''' '''#deprecated 4 ''message'''''

The effect of this directive depends on whether it appears within a macro definition.

* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.

Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)

If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

Note that except during an actual game, '''MULTIPLAYER''', '''EDITOR''' and previous campaign defines, are not guaranteed to be undefined, especially when coming back to the titlescreen. So it is not enough to hide contents inside of an #ifdef to prevent them from being seen by the campaign selection dialog, for example for multiplayer specific '''[campaign]'''s or '''[modification]'''s '''type=mp''' must be used.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line). Can also be set by typing <code>:</code> to bring up [[CommandMode]], then typing <code>debug</code>, and then restarting the scenario.
* '''APPLE''': defined while processing the main game data when running on Mac OS X. This primarily exists to switch Control for Command in hotkeys, which is why there are no defines for other platforms.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.
* '''CURRENT_FILE''': Expands to the name of the current WML file.
* '''CURRENT_DIRECTORY''': Expands to the preprocessor path of the parent directory for the current WML file (e.g. for <code><user data dir>/data/add-ons/My_Addon/_main.cfg</code> this evaluates to <code>~add-ons/My_Addon</code>).
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.
* '''SCHEMA_VALIDATION''': defined if the validator is being run.
* '''__WMLUNITS__''': defined when the tool to create [https://units.wesnoth.org units.wesnoth.org] is being run.

A ''very large'' number of additional macros are provided as part of the default game core WML. For a full list of those, check the [https://www.wesnoth.org/macro-reference.html macro reference].

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will first preprocess '''data/core/macros''' and '''data/core/terrain-graphics''', and afterwards the specified path. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulting preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the current directory.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
-p data/gui/macros/_initial.cfg /tmp --preprocess-output-macros=macros
-p myfile.cfg ~/result --preprocess-input-macros=/tmp/macros

When it starts getting complicated, such as a file that depends on multiple other files, it is probably easiest to simply "include" the dependencies:

* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
Add {gui/macros/_initial.cfg} to the beginning of myfile.cfg
-p myfile.cfg ~/result

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]] (explains relationship between comments and preprocessor directives)
* [[ReferenceWML]]

[[Category: WML Reference]]

GUIWidgetInstanceWML

2026-03-12T05:52:03Z

Bssarkar: /* Subtag [option] */ add value

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| use_markup
| | [[GUIVariable#bool|bool]]
| false
| Whether [https://docs.gtk.org/Pango/pango_markup.html Pango Markup] could be used to format the `label` of this widget (bold, italic, font color, alpha etc.)
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* '''0:''' no border.
* '''1:''' 1 pixel border.
* '''2:''' floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
|-
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
|-
|"quit"||-2||An alias for cancel
|-
|""||N/A||Clears any previously set return_value_id
|}

== Combobox ==
{{DevFeature1.19|0}}
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| value || [[GUIVariable#string|string]] || "" || Value of the option. Defaults to <code>label</code> if unspecified.
|-
| label || [[GUIVariable#t_string|t_string]] || "" || User visible translatable name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image whose path is specified by its '''[[GUIWidgetInstanceWML#Widget|label]]''' key. Unlike other widgets, the '''label''' key here is not translatable since it specifies a path. The path is a standard WML path, i.e., <code>label="units/konrad.png"</code> or <code>label="~add-ons/MyAddon/image/test.png"</code>.

It has no other extra fields.

== Label ==
A label displays text provided via the '''[[GUIWidgetInstanceWML#Widget|label]]''' key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the [[GUIWidgetInstanceWML#Scroll_Label|Scroll Label]] widget.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. This is only an approximate means of limiting the line's length, since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies '''wrap''' is true.
When having long strings, wrapping them can increase readability. A rule of thumb is 66 characters per line is considered the optimum for a one column text.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
{{DevFeature1.17|26}}

Base class for a multiline text area. Not to be used directly in a GUI, use the [[GUIWidgetInstanceWML#Scroll_Text|scroll_text]] widget instead.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
{{DevFeature1.19|x}}

A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| padding || [[GUIVariable#int|int]] || 5 || Internal padding, used in various spaces and between different types of elements (for example, between two float image, between a header and following text and so on).
|-
| link_aware || [[GUIVariable#bool|bool]] || true || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll Label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scroll Text ==
{{DevFeature1.19|x}}

A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Spinner ==
{{DevFeature1.17|26}}

[[File:Spinner.png|thumb|right]]

A textbox with two repeating buttons, which allow increasing/decreasing of the numerical value inside the textbox.

{| class="wikitable"
!key
!type
!default
!description
|-
| wrap
| [[GUIVariable#bool|bool]]
| 0
| Should the contents of the textbox wrap?
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==
{{DevFeature1.19|0}}

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If true, a tree with at least one item will always have something selected (except when items are being deleted). Although this is {{DevFeature1.19|21}}, the previous behavior is equivalent to setting this to true. The GUI doesn't provide a way to unselect items, the purpose of setting this to false is to add a landing page, as the campaign menu does.
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUIWidgetInstanceWML

2026-03-07T06:21:33Z

Bssarkar: /* Rich Label */ RL width is automatic as of 1.19.21

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| use_markup
| | [[GUIVariable#bool|bool]]
| false
| Whether [https://docs.gtk.org/Pango/pango_markup.html Pango Markup] could be used to format the `label` of this widget (bold, italic, font color, alpha etc.)
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* '''0:''' no border.
* '''1:''' 1 pixel border.
* '''2:''' floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
|-
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
|-
|"quit"||-2||An alias for cancel
|-
|""||N/A||Clears any previously set return_value_id
|}

== Combobox ==
{{DevFeature1.19|0}}
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image whose path is specified by its '''[[GUIWidgetInstanceWML#Widget|label]]''' key. Unlike other widgets, the '''label''' key here is not translatable since it specifies a path. The path is a standard WML path, i.e., <code>label="units/konrad.png"</code> or <code>label="~add-ons/MyAddon/image/test.png"</code>.

It has no other extra fields.

== Label ==
A label displays text provided via the '''[[GUIWidgetInstanceWML#Widget|label]]''' key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the [[GUIWidgetInstanceWML#Scroll_Label|Scroll Label]] widget.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. This is only an approximate means of limiting the line's length, since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies '''wrap''' is true.
When having long strings, wrapping them can increase readability. A rule of thumb is 66 characters per line is considered the optimum for a one column text.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
{{DevFeature1.17|26}}

Base class for a multiline text area. Not to be used directly in a GUI, use the [[GUIWidgetInstanceWML#Scroll_Text|scroll_text]] widget instead.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
{{DevFeature1.19|x}}

A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| padding || [[GUIVariable#int|int]] || 5 || Internal padding, used in various spaces and between different types of elements (for example, between two float image, between a header and following text and so on).
|-
| link_aware || [[GUIVariable#bool|bool]] || true || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll Label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scroll Text ==
{{DevFeature1.19|x}}

A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Spinner ==
{{DevFeature1.17|26}}

[[File:Spinner.png|thumb|right]]

A textbox with two repeating buttons, which allow increasing/decreasing of the numerical value inside the textbox.

{| class="wikitable"
!key
!type
!default
!description
|-
| wrap
| [[GUIVariable#bool|bool]]
| 0
| Should the contents of the textbox wrap?
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==
{{DevFeature1.19|0}}

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If true, a tree with at least one item will always have something selected (except when items are being deleted). Although this is {{DevFeature1.19|21}}, the previous behavior is equivalent to setting this to true. The GUI doesn't provide a way to unselect items, the purpose of setting this to false is to add a landing page, as the campaign menu does.
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

LuaAPI/types/widget

2026-02-16T15:19:47Z

Bssarkar: /* Widget Callbacks */ Sort subsections

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== best_slider_length ===
* ''widget''.'''best_slider_length''' ↔ ''length''
* Available on: '''[slider]'''
Best length of the slider.

=== characters_per_line ===
* ''widget''.'''label''' ↔ ''int''
* Available on: '''[label]'''
Maximum characters this label should show per line.

=== editable ===
* ''widget''.'''enabled''' ↔ ''boolean''
* Available on: '''[text_box]'''
If this text box is editable, i.e., read-only. (Text can be selected/copied but not modified.)

=== ellipsize_mode ===
* ''widget''.'''ellipsize_mode''' ↔ ''ellipsization mode string''
* Available on: Most widgets
Sets the [https://docs.gtk.org/Pango/enum.EllipsizeMode.html Pango ellipsization mode] for the widget. Accepts only one of the special strings:
{| clasS="wikitable"
! String value
|-
| none
|-
| start
|-
| end
|-
| middle
|-
|}

=== enabled ===
* ''widget''.'''enabled''' ↔ ''boolean''
* Available on: Most widgets

=== help ===
* ''widget''.'''enabled''' ↔ ''text''
* Available on: Most widgets
Help text for this widget.

=== hint_image ===
* ''widget''.'''hint_image''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''
A image that is shown on the widget when it is not focused and has no other text.

=== hint_text ===
* ''widget''.'''hint_text''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''
A background text that is shown on the widget when it is not focused and has no other text.

=== history ===
* ''widget''.'''history''' ← ''text''
* Available on: '''[text_box]'''
Input history of this text box.

=== indentation_step_size ===
* ''widget''.'''indentation_step_size''' ↔ ''int''
* Available on: '''[tree_view]'''
How much should child nodes be offset from their parent node.

=== item_count ===
* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''
The number of items in the container widget.

=== label ===
* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''
The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== link_aware ===
* ''widget''.'''link_aware''' → ''boolean''
* Available on: '''[label]''', '''[rich_label]''', '''[scroll_label]''', '''[scroll_text]'''
Whether this widget recognizes inline links and allows clicking on them.

=== link_color ===
* ''widget''.'''link_color''' → ''color string''
* Available on: '''[label]''', '''[rich_label]'''
Color of the inline link, as an hex string.

=== marked_up_text ===
* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''
Shortcut for setting label and use_markup=yes.

=== maximum_value_label ===
* ''widget''.'''maximum_value_label''' ↔ ''text''
* Available on: '''[slider]'''
The text the slider's label shows when it is at maximum value position.

=== max_input_length ===
* ''widget''.'''max_input_length''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''
Maximum number of character than can be input into this widget.

=== minimum_value_label ===
* ''widget''.'''minimum_value_label''' ↔ ''text''
* Available on: '''[slider]'''
The text the slider's label shows when it is at minimum value position.

=== overflow_to_tooltip ===
* ''widget''.'''overflow_to_tooltip''' ↔ ''boolean''
* Available on: Most widgets

=== path ===
* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''
A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== percentage ===
* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''
The current position of the progress bar, between 0 and 100.

=== selected ===
* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''
Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===
* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''
The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.
For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.
For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== selected_item_path ===
* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''
A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.
+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== step_size ===
* ''widget''.'''step_size''' ↔ ''int''
* Available on: '''[slider]'''

=== text ===
* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''
The text of the textbox.

=== text_alignment ===
* ''widget''.'''text_alignment''' ↔ ''text alignment string''
* Available on: Most widgets
Sets the [https://docs.gtk.org/Pango/enum.Alignment.html Pango text alignment] for the widget. Accepts only one of the special strings:
{| clasS="wikitable"
! String value
|-
| left
|-
| right
|-
| center
|-
|}

=== tooltip ===
* ''widget''.'''tooltip''' ↔ ''text''
* Available on: Most widgets

=== type ===
* ''widget''.'''type''' → ''string''
* Available on: All widgets
Returns a string specifying the type of the widget.

=== unfolded ===
* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''
Control whether a tree node is currently expanded or not.

=== unit ===
* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''
Change the displayed unit or unit type in the preview pane.

=== use_markup ===
* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''
Sets whether the widget's label will parse [[Pango formatting]].

=== value ===
* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''
The current position of the slider.

=== visible ===
* ''widget''.'''visible''' ↔ ''visibility string''
* Available on: Most widgets
Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== wrap ===
* ''widget''.'''wrap''' → ''boolean''
* Available on: '''[label]'''
Whether the text content in this label can wrap.

== Widget Callbacks ==

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T15:16:18Z

Bssarkar: /* Widget Attributes */ Sort attributes alphabetically. (via some find&replace and Linux `sort` utility)

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== best_slider_length ===
* ''widget''.'''best_slider_length''' ↔ ''length''
* Available on: '''[slider]'''
Best length of the slider.

=== characters_per_line ===
* ''widget''.'''label''' ↔ ''int''
* Available on: '''[label]'''
Maximum characters this label should show per line.

=== editable ===
* ''widget''.'''enabled''' ↔ ''boolean''
* Available on: '''[text_box]'''
If this text box is editable, i.e., read-only. (Text can be selected/copied but not modified.)

=== ellipsize_mode ===
* ''widget''.'''ellipsize_mode''' ↔ ''ellipsization mode string''
* Available on: Most widgets
Sets the [https://docs.gtk.org/Pango/enum.EllipsizeMode.html Pango ellipsization mode] for the widget. Accepts only one of the special strings:
{| clasS="wikitable"
! String value
|-
| none
|-
| start
|-
| end
|-
| middle
|-
|}

=== enabled ===
* ''widget''.'''enabled''' ↔ ''boolean''
* Available on: Most widgets

=== help ===
* ''widget''.'''enabled''' ↔ ''text''
* Available on: Most widgets
Help text for this widget.

=== hint_image ===
* ''widget''.'''hint_image''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''
A image that is shown on the widget when it is not focused and has no other text.

=== hint_text ===
* ''widget''.'''hint_text''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''
A background text that is shown on the widget when it is not focused and has no other text.

=== history ===
* ''widget''.'''history''' ← ''text''
* Available on: '''[text_box]'''
Input history of this text box.

=== indentation_step_size ===
* ''widget''.'''indentation_step_size''' ↔ ''int''
* Available on: '''[tree_view]'''
How much should child nodes be offset from their parent node.

=== item_count ===
* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''
The number of items in the container widget.

=== label ===
* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''
The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== link_aware ===
* ''widget''.'''link_aware''' → ''boolean''
* Available on: '''[label]''', '''[rich_label]''', '''[scroll_label]''', '''[scroll_text]'''
Whether this widget recognizes inline links and allows clicking on them.

=== link_color ===
* ''widget''.'''link_color''' → ''color string''
* Available on: '''[label]''', '''[rich_label]'''
Color of the inline link, as an hex string.

=== marked_up_text ===
* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''
Shortcut for setting label and use_markup=yes.

=== maximum_value_label ===
* ''widget''.'''maximum_value_label''' ↔ ''text''
* Available on: '''[slider]'''
The text the slider's label shows when it is at maximum value position.

=== max_input_length ===
* ''widget''.'''max_input_length''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''
Maximum number of character than can be input into this widget.

=== minimum_value_label ===
* ''widget''.'''minimum_value_label''' ↔ ''text''
* Available on: '''[slider]'''
The text the slider's label shows when it is at minimum value position.

=== overflow_to_tooltip ===
* ''widget''.'''overflow_to_tooltip''' ↔ ''boolean''
* Available on: Most widgets

=== path ===
* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''
A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== percentage ===
* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''
The current position of the progress bar, between 0 and 100.

=== selected ===
* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''
Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===
* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''
The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.
For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.
For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== selected_item_path ===
* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''
A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.
+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== step_size ===
* ''widget''.'''step_size''' ↔ ''int''
* Available on: '''[slider]'''

=== text ===
* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''
The text of the textbox.

=== text_alignment ===
* ''widget''.'''text_alignment''' ↔ ''text alignment string''
* Available on: Most widgets
Sets the [https://docs.gtk.org/Pango/enum.Alignment.html Pango text alignment] for the widget. Accepts only one of the special strings:
{| clasS="wikitable"
! String value
|-
| left
|-
| right
|-
| center
|-
|}

=== tooltip ===
* ''widget''.'''tooltip''' ↔ ''text''
* Available on: Most widgets

=== type ===
* ''widget''.'''type''' → ''string''
* Available on: All widgets
Returns a string specifying the type of the widget.

=== unfolded ===
* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''
Control whether a tree node is currently expanded or not.

=== unit ===
* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''
Change the displayed unit or unit type in the preview pane.

=== use_markup ===
* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''
Sets whether the widget's label will parse [[Pango formatting]].

=== value ===
* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''
The current position of the slider.

=== visible ===
* ''widget''.'''visible''' ↔ ''visibility string''
* Available on: Most widgets
Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== wrap ===
* ''widget''.'''wrap''' → ''boolean''
* Available on: '''[label]'''
Whether the text content in this label can wrap.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T04:40:36Z

Bssarkar: /* Widget Attributes */ Docs for more attrs in c2b2664eb21585a67afbb7bff931fb7b169eea47

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== indentation_step_size ===

* ''widget''.'''indentation_step_size''' ↔ ''int''
* Available on: '''[tree_view]'''

How much should child nodes be offset from their parent node.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== hint_text ===
* ''widget''.'''hint_text''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''

A background text that is shown on the widget when it is not focused and has no other text.

=== hint_image ===
* ''widget''.'''hint_image''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''

A image that is shown on the widget when it is not focused and has no other text.

=== history ===

* ''widget''.'''history''' ← ''text''
* Available on: '''[text_box]'''

Input history of this text box.

=== max_input_length ===

* ''widget''.'''max_input_length''' ↔ ''text''
* Available on: '''[text_box]''', '''[combobox]'''

Maximum number of character than can be input into this widget.

=== link_aware ===
* ''widget''.'''link_aware''' → ''boolean''
* Available on: '''[label]''', '''[rich_label]''', '''[scroll_label]''', '''[scroll_text]'''

Whether this widget recognizes inline links and allows clicking on them.

=== link_color ===
* ''widget''.'''link_color''' → ''color string''
* Available on: '''[label]''', '''[rich_label]'''

Color of the inline link, as an hex string.

=== wrap ===
* ''widget''.'''wrap''' → ''boolean''
* Available on: '''[label]'''

Whether the text content in this label can wrap.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== best_slider_length ===

* ''widget''.'''best_slider_length''' ↔ ''length''
* Available on: '''[slider]'''

Best length of the slider.

=== minimum_value_label ===

* ''widget''.'''minimum_value_label''' ↔ ''text''
* Available on: '''[slider]'''

The text the slider's label shows when it is at minimum value position.

=== maximum_value_label ===

* ''widget''.'''maximum_value_label''' ↔ ''text''
* Available on: '''[slider]'''

The text the slider's label shows when it is at maximum value position.

=== step_size ===

* ''widget''.'''step_size''' ↔ ''int''
* Available on: '''[slider]'''

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== characters_per_line ===
* ''widget''.'''label''' ↔ ''int''
* Available on: '''[label]'''

Maximum characters this label should show per line.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ↔ ''boolean''
* Available on: Most widgets

=== editable ===

* ''widget''.'''enabled''' ↔ ''boolean''
* Available on: '''[text_box]'''

If this text box is editable, i.e., read-only. (Text can be selected/copied but not modified.)

=== help ===
* ''widget''.'''enabled''' ↔ ''text''
* Available on: Most widgets

Help text for this widget.

=== tooltip ===

* ''widget''.'''tooltip''' ↔ ''text''
* Available on: Most widgets

=== overflow_to_tooltip ===

* ''widget''.'''overflow_to_tooltip''' ↔ ''boolean''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ↔ ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== ellipsize_mode ===

* ''widget''.'''ellipsize_mode''' ↔ ''ellipsization mode string''
* Available on: Most widgets

Sets the [https://docs.gtk.org/Pango/enum.EllipsizeMode.html Pango ellipsization mode] for the widget. Accepts only one of the special strings:
{| clasS="wikitable"
! String value
|-
| none
|-
| start
|-
| end
|-
| middle
|-
|}

=== text_alignment ===

* ''widget''.'''text_alignment''' ↔ ''text alignment string''
* Available on: Most widgets

Sets the [https://docs.gtk.org/Pango/enum.Alignment.html Pango text alignment] for the widget. Accepts only one of the special strings:
{| clasS="wikitable"
! String value
|-
| left
|-
| right
|-
| center
|-
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:58:56Z

Bssarkar: /* maximum_value_label */

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== best_slider_length ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

Best length of the slider.

=== minimum_value_label ===

* ''widget''.'''value''' ↔ ''text''
* Available on: '''[slider]'''

The text the slider's label shows when it is at minimum value position.

=== maximum_value_label ===

* ''widget''.'''value''' ↔ ''text''
* Available on: '''[slider]'''

The text the slider's label shows when it is at maximum value position.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== characters_per_line ===
* ''widget''.'''label''' ← ''int''
* Available on: '''[label]'''

Maximum characters this label should show per line.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:58:47Z

Bssarkar: /* minimum_value_label */ label -> text

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== best_slider_length ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

Best length of the slider.

=== minimum_value_label ===

* ''widget''.'''value''' ↔ ''text''
* Available on: '''[slider]'''

The text the slider's label shows when it is at minimum value position.

=== maximum_value_label ===

* ''widget''.'''value''' ↔ ''label''
* Available on: '''[slider]'''

The text the slider's label shows when it is at maximum value position.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== characters_per_line ===
* ''widget''.'''label''' ← ''int''
* Available on: '''[label]'''

Maximum characters this label should show per line.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:58:23Z

Bssarkar: /* label */ add characters_per_line (c2b2664eb21585a67afbb7bff931fb7b169eea47)

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== best_slider_length ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

Best length of the slider.

=== minimum_value_label ===

* ''widget''.'''value''' ↔ ''label''
* Available on: '''[slider]'''

The text the slider's label shows when it is at minimum value position.

=== maximum_value_label ===

* ''widget''.'''value''' ↔ ''label''
* Available on: '''[slider]'''

The text the slider's label shows when it is at maximum value position.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== characters_per_line ===
* ''widget''.'''label''' ← ''int''
* Available on: '''[label]'''

Maximum characters this label should show per line.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:54:00Z

Bssarkar: /* value */ Info for more attributes as of c2b2664eb21585a67afbb7bff931fb7b169eea47

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== best_slider_length ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

Best length of the slider.

=== minimum_value_label ===

* ''widget''.'''value''' ↔ ''label''
* Available on: '''[slider]'''

The text the slider's label shows when it is at minimum value position.

=== maximum_value_label ===

* ''widget''.'''value''' ↔ ''label''
* Available on: '''[slider]'''

The text the slider's label shows when it is at maximum value position.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:49:14Z

Bssarkar: /* unfolded */

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]''', '''[tree_view]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]''', '''[combobox]''', '''[stacked_widget]''', '''[tree_view]''', '''[tree_view_node]''', '''[styled_widget]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget Callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_double_click ===
{{DevFeature1.19|14}}

* ''widget''.'''on_double_click''' ← '''function'''()
* Available on: '''[toggle_panel]'''

Triggers when the user double clicks on the widget. Non-toggle panel widgets can be wrapped in a toggle panel to make use of this event handler.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

=== on_link_click ===
{{DevFeature1.19|9}}

* ''widget''.'''on_link_click''' ← '''function'''(''dest'')
* Available on: '''[rich_label]'''

Triggers when the user clicks on a '''<ref>''' link inside a '''[rich_label]'''. The first argument '''dest''' is the target of the link.

== Widget Length ==

{{DevFeature1.19|4}}

* '''#'''''widget''
* Available on: '''[listbox]''', '''[multi_page]''', '''[tree_view]''', '''[tree_view_node]''', {{DevFeature1.19|6}} '''[stacked_widget]'''

Returns the total number of children in the specified container widget – for example, the number of rows in a list box, or the number of pages in a multi-page.

== Widget Methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:48:48Z

Bssarkar: /* item_count */ Extra support as of c2b2664eb21585a67afbb7bff931fb7b169eea47

Android

2026-02-13T09:11:17Z

Bssarkar: /* Dev Notes */ add info about manifest.txt and status.properties files. syntax info will be added later.

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.
* Long press on any hex to show the Right-click context menu that has Recruit/Recall etc.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

== Dev Notes ==
=== Package manifest (manifest.txt) and download status file (status.properties) ===
{{DevFeature1.19|19}}

The package manifest file (<code>manifest.txt</code>) is a file on the Wesnoth sourceforge site that the Android Wesnoth client reads to figure out available packages for download. For example, for Wesnoth 1.19.19 it is located here: [https://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.19.19/android-data/manifest.txt/download manifest.txt]. This path is mostly hardcoded [https://github.com/wesnoth/wesnoth/blob/ff3ad482074d2698762cffcad08660c77ea1bb2c/packaging/android/app/src/main/java/org/wesnoth/Wesnoth/InitActivity.java#L66-L67 here] with only the version code part changing per release.

The <code>status.properties</code> file is generated by the Android client to track details of downloaded packages, and is created inside <code>/sdcard/Android/data/org.wesnoth.Wesnoth/files/gamedata</code>.

=== Version Code scheme (1191601001 - post 1.19.16 fixup) ===
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

=== New Version Code scheme draft ===
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

=== Other version code scheme drafts ===

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

==== <code>MMMPPpxxVA</code> ====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - Build variant (0 is clean, 1 might be google play integrations. Could be a bitfield or an enum)
* A - ABI (as above)
* x - Unspecified, available for expanding these fields or adding other flags

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, default (clean) variant, arm64

==== <code>12MMMPPpVA</code> ====
Basically the same thing, just shifted to the right by eating up the unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 clean arm64, as above.

==== <code>12MMPPpxVA</code> ====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 clean arm64, as above.

Android

2026-02-13T08:55:01Z

Bssarkar: /* Dev Notes */ Promote section header levels

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.
* Long press on any hex to show the Right-click context menu that has Recruit/Recall etc.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

== Dev Notes ==
=== Version Code scheme (1191601001 - post 1.19.16 fixup) ===
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

=== New Version Code scheme draft ===
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

=== Other version code scheme drafts ===

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

==== <code>MMMPPpxxVA</code> ====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - Build variant (0 is clean, 1 might be google play integrations. Could be a bitfield or an enum)
* A - ABI (as above)
* x - Unspecified, available for expanding these fields or adding other flags

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, default (clean) variant, arm64

==== <code>12MMMPPpVA</code> ====
Basically the same thing, just shifted to the right by eating up the unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 clean arm64, as above.

==== <code>12MMPPpxVA</code> ====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 clean arm64, as above.

UnitsWML

2026-01-29T14:05:40Z

Bssarkar: /* [trait] */ fix typo

{{WML Tags}}

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

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

== Subtags of [units] ==

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

=== [unit_type] ===

{{Main|UnitTypeWML}}

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

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

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

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

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

=== [trait] ===

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

=== [movetype] ===

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

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

=== [race] ===

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

=== [resistance_defaults] ===

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

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

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

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

=== [terrain_defaults] ===

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

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

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

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

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

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

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

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

=== [hide_help] ===

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

== See Also ==

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

[[Category: WML Reference]]

Authoring tools

2026-01-09T01:46:55Z

Bssarkar: /* Wesnoth Map Tracker */ fixup

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML.

== tmx_trackplacer ==

{{DevFeature1.15|3}} '''tmx_trackplacer''' is a tool for editing journey tracks - the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

You'll need Tiled, a GPLv2 map editor:
* Debian / Ubuntu: install the "tiled" package
* other platforms: https://www.mapeditor.org/
* these instructions were written with version 1.2.4

=== Usage ===

Assume the campaign that we want to make a map for is Story of Wose, which is set on the Green Isle. Start by putting a copy of the map in the campaign:

mkdir Story_of_Wose/images/maps
cp WESNOTH_DIR/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Story_of_Wose/images/maps/

Create a template .tmx file with the tool:

WESNOTH_DIR/data/tools/tmx_trackplacer Story_of_Wose/images/maps/green_isle.png -o temp.tmx

=== In Tiled ===

Start Tiled with the temp.tmx file. Expect to see the Green Isle map. On the right hand side of the screen there should be two windows:
* in the top, tabs ''Minimap'', ''Objects'' and ''Layers''. The Layers tab will have only ''background''.
* in the bottom, tabs ''Terrains'' and ''Tilesets''. The Tilesets tab should have ''wesnoth journey icons'' with the red dot, battle and rest markers.
https://user-images.githubusercontent.com/101462/66930950-ac876c80-f035-11e9-9599-d5dc4301acf2.png

In Layers, create a ''New Layer'' of type ''Object Layer''. A typical name for this layer is '''JOURNEY'''. Ensure that this layer is selected.
From the menu bar at the top, select ''Insert Tile''.
From the Tilesets tab, choose dots, battles or rests, and click on the map to add them. The first two items placed will define the start of the journey; every item placed after the first two will be inserted in to the sequence based on whether it appears to be at the end or in the middle.

For Story of Wose, the journey doubles back on itself. For this we'll split the journey in to two parts - rename '''JOURNEY''' to '''JOURNEY_PART1''', and add a new layer '''JOURNEY_PART2'''. You can use the opacity control at the top of the layers window to see what's on each layer.

'''JOURNEY_PART1''' starts with a battle, and ends with a battle:
https://user-images.githubusercontent.com/101462/66930947-abeed600-f035-11e9-89e8-efde15f2a48d.png

'''JOURNEY_PART2''' starts with dots, has a battle and then ends with another battle:
https://user-images.githubusercontent.com/101462/66930949-abeed600-f035-11e9-86a0-18c90c151c76.png

Save the .tmx file.

=== Creating the .cfg ===

Convert the .tmx file to a .cfg file:

WESNOTH_DIR/data/tools/tmx_trackplacer temp.tmx -o Story_of_Wose/utils/bigmap.cfg

Expect to see:

Read data: <Journey based on map file 'Story_of_Wose/images/maps/green_isle.png', with tracks {JOURNEY_PART1,JOURNEY_PART2}>
Exporting as cfg

At the moment, tmx_trackplacer doesn't have a way to preview the animations, other than loading the .cfg with Wesnoth itself. For testing, let's put all of the journey in at the start of the first scenario, Story_of_Wose/scenarios/1_The_Oldwood.cfg

#define STORY_BACKGROUND
[background_layer]
image=maps/background.jpg
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
[/background_layer]
[background_layer]
image=maps/green_isle.png
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
base_layer=yes
[/background_layer]
#enddef

[story]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE2}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE2}
[/part]
[part]
story= _ "Today I want to tell you another story, a mere footnote in the history books if it is even remembered at all."

This should now show at the start of the campaign. Remember to refresh Wesnoth's cache if it doesn't appear.

=== Could this be integrated as a Tiled plugin? ===

Yes it could. Implementing it as a file converter was the easier option for development, and the code is (hopefully) modular enough for reuse.

== trackviewer ==

{{DevFeature1.15|3}} Map journey track animation preview tool, shows the journey without needing to start Wesnoth and refresh the cache. It’s a support program which assumes you’re either editing the .cfg file with a text editor or using Tiled with [[Authoring_tools#tmx_trackplacer|tmx_trackplacer]]; in other words, it's the part of the [[Authoring_tools#trackplacer|old trackplacer]] that wasn't covered by tmx_trackplacer.

At least on Linux you can have both Tiled and this open on the same file. Save the file in Tiled, alt+tab to this, and press enter to reload the file.

Keys:
* Escape quits
* Return or Enter reloads the .cfg or .tmx file, and restarts the animation
* Space pauses/unpauses

== trackplacer ==

'''UPDATE: per Elvish_Hunter in [https://forums.wesnoth.org/viewtopic.php?f=21&t=48478&p=631121#p631121 this thread]:
'''<nowiki>"trackplacer is outdated (it requires the obsolete PyGTK toolkit, which doesn't run on Python 3) and terribly bugged (it doesn't run at all on Windows, for example)."</nowiki> You should either use [[Authoring tools#tmx_trackplacer|tmx_trackplacer]], or use image editing software to find the X and Y coordinates to create each dot or cross manually.
-------------

'''trackplacer''' is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run '''trackplacer''', it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by '''trackplacer''' (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the '''trackplacer''' window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, '''trackplacer''' looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The '''Animate''' button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The '''Save''' button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The '''Properties''' button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of '''trackplacer'''. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to '''JOURNEY''').

The '''Tracks''' button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like '''JOURNEY_STAGE_1''', '''JOURNEY_STAGE_2''' and so on. '''JOURNEY_STAGE_1''' will draw the first stage in the 'new' color parts. '''JOURNEY_STAGE_2''' will draw the first stage in the 'old' color and the second stage in the 'new' one; '''JOURNEY_STAGE_3''' will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro '''JOURNEY_COMPLETE''' that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments
that look like this:

# trackplacer: tracks begin
# trackplacer: tracks end

'''trackplacer''' will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your ''journey.cfg'', looking like this:

<tt># trackplacer: <property>=<value></tt>

These set properties that '''trackplacer''' may use. At present there is only one such property: <tt>map</tt>, which records the name of the mapfile on which your track is laid. Don't remove this comment, '''trackplacer''' needs it.

'''trackplacer''' has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click '''Animate''' to refresh and slow down.

== CampSynt==

'''CampSynt''' is a tool to create a not so skeletal campaign as you can view in the help:

camp-synt -c -n -s [-s] -h [-h] -u [-u] -f -w

Warning: put underscores instead of spaces or include in double quotes (eg: a_string or "a string")
Warning: you can use long or short notations for options:
-c A_str is the same of -c "A str" and of --campaign=A_str and --campaign="A str"

OPTIONS:
-c Name_with_underscores or "Name in quotes". This option is mandatory.
-n Number of scenarios if not provided scenario's names via -s option
-s First_scenario [-s Second_scenario -s Third_scenario -s End]
one or more scenario names provided in sequential order
-h Hero_Name [-h Best_Friend -h My_Dog.Wolf]
one or more hero names to create and use in the story.
If the name contains a '.' (dot sign) everything following it is considerd as the type of that unit.
-u new_Unit [-u Another_one -u Last]
one or more new unit types to be included in the private units folder.
If the name contains two dot signs it will be splitted this way: new_unit_name, race, copied_from
like in: Farm_rebel.humans.Peasant
This need -w option properly set.
-f Force the rewrite of an existing file.
-w Wesnoth path (in double quotes if containing spaces) to access original units.
If this option is set and the path match 1.6 then the directory 'campaigns' is used instead of 'add-ons'.

EXAMPLES:
-c Camp_Name -n 3
-c Camp_Name -n 3 -f
-c Camp_Name -s Scenario_One -s Scenario_Two
-c Camp_Name -s Scenario_One -s Scenario_Two -h Hero_Name -u New_unit
-c Camp_Name -s One -s Two -h Hero_Name -h His_Friend -u New_unit -u New_Bowman
-c Camp_Name -s One -s Two -h Hero -h Friend.New_Bowman -u New_Bowman
-c Camp_Name -s One -s Two -h Hero.New_Bowman -u New_Bowman.humans.Peasant

campsynth is a perl script (with core modules usage only, suitable for most Linux systems and packed as exe for the enjoy of some other OS users). It was written based on 1.8.5 version of the game but can be also used with 1.6.x versions and was successfully tested with 1.9.5 (12 apr 2011). campsynth is located at the forum http://forum.wesnoth.org/viewtopic.php?f=8&t=29010

== Wesnoth Map Tracker ==
A standalone free and open source GUI tool that is available from here: https://github.com/babaissarkar/WesnothMapTracker

It allows you to open an image file (say the Wesnoth Map) and place markers upon it, and the corresponding macro code is generated like this:
<syntaxhighlight lang=wml>
{NEW_JOURNEY 455 300}
{NEW_REST 500 300}
</syntaxhighlight>

Note that it cannot generate a full map.cfg yet, just the part mentioned. For detailed instructions please visit the link above.

[[Category:Tools]]

Authoring tools

2026-01-09T01:46:22Z

Bssarkar: /* Wesnoth Map Tracker */ use syntaxhighlight

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML.

== tmx_trackplacer ==

{{DevFeature1.15|3}} '''tmx_trackplacer''' is a tool for editing journey tracks - the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

You'll need Tiled, a GPLv2 map editor:
* Debian / Ubuntu: install the "tiled" package
* other platforms: https://www.mapeditor.org/
* these instructions were written with version 1.2.4

=== Usage ===

Assume the campaign that we want to make a map for is Story of Wose, which is set on the Green Isle. Start by putting a copy of the map in the campaign:

mkdir Story_of_Wose/images/maps
cp WESNOTH_DIR/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Story_of_Wose/images/maps/

Create a template .tmx file with the tool:

WESNOTH_DIR/data/tools/tmx_trackplacer Story_of_Wose/images/maps/green_isle.png -o temp.tmx

=== In Tiled ===

Start Tiled with the temp.tmx file. Expect to see the Green Isle map. On the right hand side of the screen there should be two windows:
* in the top, tabs ''Minimap'', ''Objects'' and ''Layers''. The Layers tab will have only ''background''.
* in the bottom, tabs ''Terrains'' and ''Tilesets''. The Tilesets tab should have ''wesnoth journey icons'' with the red dot, battle and rest markers.
https://user-images.githubusercontent.com/101462/66930950-ac876c80-f035-11e9-9599-d5dc4301acf2.png

In Layers, create a ''New Layer'' of type ''Object Layer''. A typical name for this layer is '''JOURNEY'''. Ensure that this layer is selected.
From the menu bar at the top, select ''Insert Tile''.
From the Tilesets tab, choose dots, battles or rests, and click on the map to add them. The first two items placed will define the start of the journey; every item placed after the first two will be inserted in to the sequence based on whether it appears to be at the end or in the middle.

For Story of Wose, the journey doubles back on itself. For this we'll split the journey in to two parts - rename '''JOURNEY''' to '''JOURNEY_PART1''', and add a new layer '''JOURNEY_PART2'''. You can use the opacity control at the top of the layers window to see what's on each layer.

'''JOURNEY_PART1''' starts with a battle, and ends with a battle:
https://user-images.githubusercontent.com/101462/66930947-abeed600-f035-11e9-89e8-efde15f2a48d.png

'''JOURNEY_PART2''' starts with dots, has a battle and then ends with another battle:
https://user-images.githubusercontent.com/101462/66930949-abeed600-f035-11e9-86a0-18c90c151c76.png

Save the .tmx file.

=== Creating the .cfg ===

Convert the .tmx file to a .cfg file:

WESNOTH_DIR/data/tools/tmx_trackplacer temp.tmx -o Story_of_Wose/utils/bigmap.cfg

Expect to see:

Read data: <Journey based on map file 'Story_of_Wose/images/maps/green_isle.png', with tracks {JOURNEY_PART1,JOURNEY_PART2}>
Exporting as cfg

At the moment, tmx_trackplacer doesn't have a way to preview the animations, other than loading the .cfg with Wesnoth itself. For testing, let's put all of the journey in at the start of the first scenario, Story_of_Wose/scenarios/1_The_Oldwood.cfg

#define STORY_BACKGROUND
[background_layer]
image=maps/background.jpg
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
[/background_layer]
[background_layer]
image=maps/green_isle.png
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
base_layer=yes
[/background_layer]
#enddef

[story]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE2}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE2}
[/part]
[part]
story= _ "Today I want to tell you another story, a mere footnote in the history books if it is even remembered at all."

This should now show at the start of the campaign. Remember to refresh Wesnoth's cache if it doesn't appear.

=== Could this be integrated as a Tiled plugin? ===

Yes it could. Implementing it as a file converter was the easier option for development, and the code is (hopefully) modular enough for reuse.

== trackviewer ==

{{DevFeature1.15|3}} Map journey track animation preview tool, shows the journey without needing to start Wesnoth and refresh the cache. It’s a support program which assumes you’re either editing the .cfg file with a text editor or using Tiled with [[Authoring_tools#tmx_trackplacer|tmx_trackplacer]]; in other words, it's the part of the [[Authoring_tools#trackplacer|old trackplacer]] that wasn't covered by tmx_trackplacer.

At least on Linux you can have both Tiled and this open on the same file. Save the file in Tiled, alt+tab to this, and press enter to reload the file.

Keys:
* Escape quits
* Return or Enter reloads the .cfg or .tmx file, and restarts the animation
* Space pauses/unpauses

== trackplacer ==

'''UPDATE: per Elvish_Hunter in [https://forums.wesnoth.org/viewtopic.php?f=21&t=48478&p=631121#p631121 this thread]:
'''<nowiki>"trackplacer is outdated (it requires the obsolete PyGTK toolkit, which doesn't run on Python 3) and terribly bugged (it doesn't run at all on Windows, for example)."</nowiki> You should either use [[Authoring tools#tmx_trackplacer|tmx_trackplacer]], or use image editing software to find the X and Y coordinates to create each dot or cross manually.
-------------

'''trackplacer''' is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run '''trackplacer''', it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by '''trackplacer''' (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the '''trackplacer''' window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, '''trackplacer''' looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The '''Animate''' button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The '''Save''' button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The '''Properties''' button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of '''trackplacer'''. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to '''JOURNEY''').

The '''Tracks''' button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like '''JOURNEY_STAGE_1''', '''JOURNEY_STAGE_2''' and so on. '''JOURNEY_STAGE_1''' will draw the first stage in the 'new' color parts. '''JOURNEY_STAGE_2''' will draw the first stage in the 'old' color and the second stage in the 'new' one; '''JOURNEY_STAGE_3''' will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro '''JOURNEY_COMPLETE''' that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments
that look like this:

# trackplacer: tracks begin
# trackplacer: tracks end

'''trackplacer''' will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your ''journey.cfg'', looking like this:

<tt># trackplacer: <property>=<value></tt>

These set properties that '''trackplacer''' may use. At present there is only one such property: <tt>map</tt>, which records the name of the mapfile on which your track is laid. Don't remove this comment, '''trackplacer''' needs it.

'''trackplacer''' has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click '''Animate''' to refresh and slow down.

== CampSynt==

'''CampSynt''' is a tool to create a not so skeletal campaign as you can view in the help:

camp-synt -c -n -s [-s] -h [-h] -u [-u] -f -w

Warning: put underscores instead of spaces or include in double quotes (eg: a_string or "a string")
Warning: you can use long or short notations for options:
-c A_str is the same of -c "A str" and of --campaign=A_str and --campaign="A str"

OPTIONS:
-c Name_with_underscores or "Name in quotes". This option is mandatory.
-n Number of scenarios if not provided scenario's names via -s option
-s First_scenario [-s Second_scenario -s Third_scenario -s End]
one or more scenario names provided in sequential order
-h Hero_Name [-h Best_Friend -h My_Dog.Wolf]
one or more hero names to create and use in the story.
If the name contains a '.' (dot sign) everything following it is considerd as the type of that unit.
-u new_Unit [-u Another_one -u Last]
one or more new unit types to be included in the private units folder.
If the name contains two dot signs it will be splitted this way: new_unit_name, race, copied_from
like in: Farm_rebel.humans.Peasant
This need -w option properly set.
-f Force the rewrite of an existing file.
-w Wesnoth path (in double quotes if containing spaces) to access original units.
If this option is set and the path match 1.6 then the directory 'campaigns' is used instead of 'add-ons'.

EXAMPLES:
-c Camp_Name -n 3
-c Camp_Name -n 3 -f
-c Camp_Name -s Scenario_One -s Scenario_Two
-c Camp_Name -s Scenario_One -s Scenario_Two -h Hero_Name -u New_unit
-c Camp_Name -s One -s Two -h Hero_Name -h His_Friend -u New_unit -u New_Bowman
-c Camp_Name -s One -s Two -h Hero -h Friend.New_Bowman -u New_Bowman
-c Camp_Name -s One -s Two -h Hero.New_Bowman -u New_Bowman.humans.Peasant

campsynth is a perl script (with core modules usage only, suitable for most Linux systems and packed as exe for the enjoy of some other OS users). It was written based on 1.8.5 version of the game but can be also used with 1.6.x versions and was successfully tested with 1.9.5 (12 apr 2011). campsynth is located at the forum http://forum.wesnoth.org/viewtopic.php?f=8&t=29010

== Wesnoth Map Tracker ==
A standalone free and open source GUI tool that is available from here: https://github.com/babaissarkar/WesnothMapTracker

It allows you to open an image file (say the Wesnoth Map) and place markers upon it, and the corresponding macro code is generated like this:
of a user interface would be :
<syntaxhighlight lang=wml>
{NEW_JOURNEY 455 300}
{NEW_REST 500 300}
</syntaxhighlight>

Note that it cannot generate a full map.cfg yet, just the part mentioned. For detailed instructions please visit the link above.

[[Category:Tools]]

Authoring tools

2026-01-09T01:41:40Z

Bssarkar: Add WesnothMapTracker tool

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML.

== tmx_trackplacer ==

{{DevFeature1.15|3}} '''tmx_trackplacer''' is a tool for editing journey tracks - the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

You'll need Tiled, a GPLv2 map editor:
* Debian / Ubuntu: install the "tiled" package
* other platforms: https://www.mapeditor.org/
* these instructions were written with version 1.2.4

=== Usage ===

Assume the campaign that we want to make a map for is Story of Wose, which is set on the Green Isle. Start by putting a copy of the map in the campaign:

mkdir Story_of_Wose/images/maps
cp WESNOTH_DIR/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Story_of_Wose/images/maps/

Create a template .tmx file with the tool:

WESNOTH_DIR/data/tools/tmx_trackplacer Story_of_Wose/images/maps/green_isle.png -o temp.tmx

=== In Tiled ===

Start Tiled with the temp.tmx file. Expect to see the Green Isle map. On the right hand side of the screen there should be two windows:
* in the top, tabs ''Minimap'', ''Objects'' and ''Layers''. The Layers tab will have only ''background''.
* in the bottom, tabs ''Terrains'' and ''Tilesets''. The Tilesets tab should have ''wesnoth journey icons'' with the red dot, battle and rest markers.
https://user-images.githubusercontent.com/101462/66930950-ac876c80-f035-11e9-9599-d5dc4301acf2.png

In Layers, create a ''New Layer'' of type ''Object Layer''. A typical name for this layer is '''JOURNEY'''. Ensure that this layer is selected.
From the menu bar at the top, select ''Insert Tile''.
From the Tilesets tab, choose dots, battles or rests, and click on the map to add them. The first two items placed will define the start of the journey; every item placed after the first two will be inserted in to the sequence based on whether it appears to be at the end or in the middle.

For Story of Wose, the journey doubles back on itself. For this we'll split the journey in to two parts - rename '''JOURNEY''' to '''JOURNEY_PART1''', and add a new layer '''JOURNEY_PART2'''. You can use the opacity control at the top of the layers window to see what's on each layer.

'''JOURNEY_PART1''' starts with a battle, and ends with a battle:
https://user-images.githubusercontent.com/101462/66930947-abeed600-f035-11e9-89e8-efde15f2a48d.png

'''JOURNEY_PART2''' starts with dots, has a battle and then ends with another battle:
https://user-images.githubusercontent.com/101462/66930949-abeed600-f035-11e9-86a0-18c90c151c76.png

Save the .tmx file.

=== Creating the .cfg ===

Convert the .tmx file to a .cfg file:

WESNOTH_DIR/data/tools/tmx_trackplacer temp.tmx -o Story_of_Wose/utils/bigmap.cfg

Expect to see:

Read data: <Journey based on map file 'Story_of_Wose/images/maps/green_isle.png', with tracks {JOURNEY_PART1,JOURNEY_PART2}>
Exporting as cfg

At the moment, tmx_trackplacer doesn't have a way to preview the animations, other than loading the .cfg with Wesnoth itself. For testing, let's put all of the journey in at the start of the first scenario, Story_of_Wose/scenarios/1_The_Oldwood.cfg

#define STORY_BACKGROUND
[background_layer]
image=maps/background.jpg
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
[/background_layer]
[background_layer]
image=maps/green_isle.png
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
base_layer=yes
[/background_layer]
#enddef

[story]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE2}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE2}
[/part]
[part]
story= _ "Today I want to tell you another story, a mere footnote in the history books if it is even remembered at all."

This should now show at the start of the campaign. Remember to refresh Wesnoth's cache if it doesn't appear.

=== Could this be integrated as a Tiled plugin? ===

Yes it could. Implementing it as a file converter was the easier option for development, and the code is (hopefully) modular enough for reuse.

== trackviewer ==

{{DevFeature1.15|3}} Map journey track animation preview tool, shows the journey without needing to start Wesnoth and refresh the cache. It’s a support program which assumes you’re either editing the .cfg file with a text editor or using Tiled with [[Authoring_tools#tmx_trackplacer|tmx_trackplacer]]; in other words, it's the part of the [[Authoring_tools#trackplacer|old trackplacer]] that wasn't covered by tmx_trackplacer.

At least on Linux you can have both Tiled and this open on the same file. Save the file in Tiled, alt+tab to this, and press enter to reload the file.

Keys:
* Escape quits
* Return or Enter reloads the .cfg or .tmx file, and restarts the animation
* Space pauses/unpauses

== trackplacer ==

'''UPDATE: per Elvish_Hunter in [https://forums.wesnoth.org/viewtopic.php?f=21&t=48478&p=631121#p631121 this thread]:
'''<nowiki>"trackplacer is outdated (it requires the obsolete PyGTK toolkit, which doesn't run on Python 3) and terribly bugged (it doesn't run at all on Windows, for example)."</nowiki> You should either use [[Authoring tools#tmx_trackplacer|tmx_trackplacer]], or use image editing software to find the X and Y coordinates to create each dot or cross manually.
-------------

'''trackplacer''' is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run '''trackplacer''', it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by '''trackplacer''' (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the '''trackplacer''' window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, '''trackplacer''' looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The '''Animate''' button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The '''Save''' button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The '''Properties''' button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of '''trackplacer'''. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to '''JOURNEY''').

The '''Tracks''' button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like '''JOURNEY_STAGE_1''', '''JOURNEY_STAGE_2''' and so on. '''JOURNEY_STAGE_1''' will draw the first stage in the 'new' color parts. '''JOURNEY_STAGE_2''' will draw the first stage in the 'old' color and the second stage in the 'new' one; '''JOURNEY_STAGE_3''' will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro '''JOURNEY_COMPLETE''' that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments
that look like this:

# trackplacer: tracks begin
# trackplacer: tracks end

'''trackplacer''' will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your ''journey.cfg'', looking like this:

<tt># trackplacer: <property>=<value></tt>

These set properties that '''trackplacer''' may use. At present there is only one such property: <tt>map</tt>, which records the name of the mapfile on which your track is laid. Don't remove this comment, '''trackplacer''' needs it.

'''trackplacer''' has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click '''Animate''' to refresh and slow down.

== CampSynt==

'''CampSynt''' is a tool to create a not so skeletal campaign as you can view in the help:

camp-synt -c -n -s [-s] -h [-h] -u [-u] -f -w

Warning: put underscores instead of spaces or include in double quotes (eg: a_string or "a string")
Warning: you can use long or short notations for options:
-c A_str is the same of -c "A str" and of --campaign=A_str and --campaign="A str"

OPTIONS:
-c Name_with_underscores or "Name in quotes". This option is mandatory.
-n Number of scenarios if not provided scenario's names via -s option
-s First_scenario [-s Second_scenario -s Third_scenario -s End]
one or more scenario names provided in sequential order
-h Hero_Name [-h Best_Friend -h My_Dog.Wolf]
one or more hero names to create and use in the story.
If the name contains a '.' (dot sign) everything following it is considerd as the type of that unit.
-u new_Unit [-u Another_one -u Last]
one or more new unit types to be included in the private units folder.
If the name contains two dot signs it will be splitted this way: new_unit_name, race, copied_from
like in: Farm_rebel.humans.Peasant
This need -w option properly set.
-f Force the rewrite of an existing file.
-w Wesnoth path (in double quotes if containing spaces) to access original units.
If this option is set and the path match 1.6 then the directory 'campaigns' is used instead of 'add-ons'.

EXAMPLES:
-c Camp_Name -n 3
-c Camp_Name -n 3 -f
-c Camp_Name -s Scenario_One -s Scenario_Two
-c Camp_Name -s Scenario_One -s Scenario_Two -h Hero_Name -u New_unit
-c Camp_Name -s One -s Two -h Hero_Name -h His_Friend -u New_unit -u New_Bowman
-c Camp_Name -s One -s Two -h Hero -h Friend.New_Bowman -u New_Bowman
-c Camp_Name -s One -s Two -h Hero.New_Bowman -u New_Bowman.humans.Peasant

campsynth is a perl script (with core modules usage only, suitable for most Linux systems and packed as exe for the enjoy of some other OS users). It was written based on 1.8.5 version of the game but can be also used with 1.6.x versions and was successfully tested with 1.9.5 (12 apr 2011). campsynth is located at the forum http://forum.wesnoth.org/viewtopic.php?f=8&t=29010

== Wesnoth Map Tracker ==
A standalone free and open source GUI tool that is available from here: https://github.com/babaissarkar/WesnothMapTracker

It allows you to open an image file (say the Wesnoth Map) and place markers upon it, and the corresponding macro code is generated like this:
<code>
{NEW_JOURNEY 455 300}
{NEW_REST 500 300}
</code>

For detailed instructions please visit the link above.

[[Category:Tools]]

AbilitiesWML

2025-12-03T03:58:08Z

Bssarkar: /* Common keys and tags for specials with a value */ Add PO variables

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

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

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-12-03T03:56:53Z

Bssarkar: /* Common keys and tags for abilities with a value */ Show PO variables

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

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

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-29T03:07:34Z

Bssarkar: /* Extra keys used by the [plague] special */ Mention $type variable

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

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

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-29T03:05:00Z

Bssarkar: /* Common keys and tags for every weapon special */ Add unique_id details to weapon specials

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-29T03:03:46Z

Bssarkar: /* Common keys and tags for every ability */ only keep ability specific registry info.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-29T03:02:46Z

Bssarkar: /* Common keys and tags for every ability */ mention only ability registry

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-16T15:53:22Z

Bssarkar: /* Common keys and tags for every ability */ Update unique_id based on changed in PR 10691

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be choosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

UnitTypeWML

2025-11-16T15:49:20Z

Bssarkar: /* Attacks */ typofix

{{WML Tags}}

__TOC__

== Unit Type ==

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

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

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

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

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

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

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

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

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

== Special Notes ==

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

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

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

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

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

== Removed keys ==

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

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

== Deprecating units ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2025-11-16T15:48:58Z

Bssarkar: /* Attacks */ Add `specials_list` vide PR 10691

{{WML Tags}}

__TOC__

== Unit Type ==

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

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

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

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

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

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

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

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

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

== Special Notes ==

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

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

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

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

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

== Removed keys ==

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

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

== Deprecating units ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2025-11-16T15:46:28Z

Bssarkar: /* Other tags */ Name changed via PR 10691

{{WML Tags}}

__TOC__

== Unit Type ==

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

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

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

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''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}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

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

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

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

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

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

== Special Notes ==

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

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

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

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

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

== Removed keys ==

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

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

== Deprecating units ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitsWML

2025-11-16T15:44:18Z

Bssarkar: /* [weapon_specials] */

{{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|17}}

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|17}}

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

=== [trait] ===

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

=== [movetype] ===

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

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

=== [race] ===

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

=== [resistance_defaults] ===

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

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

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

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

=== [terrain_defaults] ===

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

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

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

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

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

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

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

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

=== [hide_help] ===

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

== See Also ==

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

[[Category: WML Reference]]

UnitsWML

2025-11-16T15:43:54Z

Bssarkar: /* [abilities] */ Add [weapon_specials] vide #10691

{{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|17}}

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|17}}

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''' by mentioning its '''unique_id''' (or '''id''' if unique_id is undefined) without the need to include the full ability definition.

=== [trait] ===

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

=== [movetype] ===

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

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

=== [race] ===

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

=== [resistance_defaults] ===

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

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

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

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

=== [terrain_defaults] ===

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

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

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

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

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

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

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

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

=== [hide_help] ===

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

== See Also ==

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

[[Category: WML Reference]]

EffectWML

2025-11-03T04:13:48Z

Bssarkar: /* [effect] */

{{WML Tags}}

== [effect] ==

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

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

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

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

== Movement and Vision ==

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

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

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

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

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

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

== Where to Use Effects ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

EffectWML

2025-11-03T04:13:04Z

Bssarkar: /* [effect] */ Add abilities key (PR #10644)

{{WML Tags}}

== [effect] ==

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

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

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

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

== Movement and Vision ==

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

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

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

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

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

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

== Where to Use Effects ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2025-11-03T03:48:47Z

Bssarkar: /* Other tags */ linkify unique_id mention

{{WML Tags}}

__TOC__

== Unit Type ==

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

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

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

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''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}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

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

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

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

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

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

== Special Notes ==

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

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

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

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

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

== Removed keys ==

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

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

== Deprecating units ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2025-11-03T03:47:19Z

Bssarkar: /* Other tags */ mark supported version

{{WML Tags}}

__TOC__

== Unit Type ==

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

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

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

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''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}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

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

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

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

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

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

== Special Notes ==

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

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

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

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

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

== Removed keys ==

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

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

== Deprecating units ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2025-11-03T03:46:33Z

Bssarkar: /* Other tags */ Add abilities key. (PR #10644)

{{WML Tags}}

__TOC__

== Unit Type ==

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

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

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

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''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}} one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

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

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

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

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

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

== Special Notes ==

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

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

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

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

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

== Removed keys ==

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

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

== Deprecating units ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

AbilitiesWML

2025-11-03T03:39:31Z

Bssarkar: /* Common keys and tags for every ability */ mark supported version

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be choosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-03T03:38:34Z

Bssarkar: /* Common keys and tags for every ability */ Mention unique_id (PR #10644) fixup

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be choosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2025-11-03T03:34:35Z

Bssarkar: /* Common keys and tags for every ability */ Mention unique_id (PR #10644)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be choosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]