The Battle for Wesnoth Wiki - User contributions [en]

GUIWidgetInstanceWML

2026-04-30T05:27:06Z

Celtic Minstrel: /* Spacer */ Don't make external link to internal page

== 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 keys in common, that can be used in any widget in addition to the widget-specific keys listed below.
{| 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 ==

[[File:Button.png|thumb|left|An example of a 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.
|}

=== Subtag [draw] ===
A mandatory WML block (config) containing the drawing instructions, in the same format as [[GUICanvasWML]]. For an example, see this snippet from the [https://github.com/wesnoth/wesnoth/blob/9bd7614e89269b5456ee51ade3cc0af73efc99f5/data/gui/themes/default/dialogs/attack_predictions.cfg#L100 Attack predictions dialog].

The variables available are the same as for the window resolution, see
[[GUIToolkitWML#Resolution_2|GUIToolkitWML]] 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.
|}

== Size lock ==
Instance of the size_lock widget. This is a special container that forces the widget enclosed in the [widget] subtag to be of the size specified by the width and height. The [https://github.com/wesnoth/wesnoth/blob/9bd7614e89269b5456ee51ade3cc0af73efc99f5/data/gui/macros/_initial.cfg#L246 GUI_FORCE_WIDGET_SIZE] internal macro is a wrapper around this component.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#int|int]]
| -
| The width the enclosed widget should be forced to (mandatory).
|-
| height
| [[GUIVariable#int|int]]
| -
| The height the enclosed widget should be forced to (mandatory).
|}

Note: Both <code>width</code> and <code>height</code> are mandatory even if you want to fix either width or height as of 1.19.23.

=== Subtag [widget] ===
The widget that should be force-sized.

== 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
[[GUIToolkitWML#Resolution_2|GUIToolkitWML]] 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-04-30T05:26:01Z

Celtic Minstrel: /* Subtag [draw] */ Don't make external link to internal page

== 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 keys in common, that can be used in any widget in addition to the widget-specific keys listed below.
{| 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 ==

[[File:Button.png|thumb|left|An example of a 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.
|}

=== Subtag [draw] ===
A mandatory WML block (config) containing the drawing instructions, in the same format as [[GUICanvasWML]]. For an example, see this snippet from the [https://github.com/wesnoth/wesnoth/blob/9bd7614e89269b5456ee51ade3cc0af73efc99f5/data/gui/themes/default/dialogs/attack_predictions.cfg#L100 Attack predictions dialog].

The variables available are the same as for the window resolution, see
[[GUIToolkitWML#Resolution_2|GUIToolkitWML]] 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.
|}

== Size lock ==
Instance of the size_lock widget. This is a special container that forces the widget enclosed in the [widget] subtag to be of the size specified by the width and height. The [https://github.com/wesnoth/wesnoth/blob/9bd7614e89269b5456ee51ade3cc0af73efc99f5/data/gui/macros/_initial.cfg#L246 GUI_FORCE_WIDGET_SIZE] internal macro is a wrapper around this component.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#int|int]]
| -
| The width the enclosed widget should be forced to (mandatory).
|-
| height
| [[GUIVariable#int|int]]
| -
| The height the enclosed widget should be forced to (mandatory).
|}

Note: Both <code>width</code> and <code>height</code> are mandatory even if you want to fix either width or height as of 1.19.23.

=== Subtag [widget] ===
The widget that should be force-sized.

== 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-04-30T05:25:40Z

Celtic Minstrel: /* Subtag [draw] */ Don't make external link to internal page

== 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 keys in common, that can be used in any widget in addition to the widget-specific keys listed below.
{| 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 ==

[[File:Button.png|thumb|left|An example of a 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.
|}

=== Subtag [draw] ===
A mandatory WML block (config) containing the drawing instructions, in the same format as [https://wiki.wesnoth.org/GUICanvasWML GUICanvasWML]. For an example, see this snippet from the [https://github.com/wesnoth/wesnoth/blob/9bd7614e89269b5456ee51ade3cc0af73efc99f5/data/gui/themes/default/dialogs/attack_predictions.cfg#L100 Attack predictions dialog].

The variables available are the same as for the window resolution, see
[[GUIToolkitWML#Resolution_2|GUIToolkitWML]] 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.
|}

== Size lock ==
Instance of the size_lock widget. This is a special container that forces the widget enclosed in the [widget] subtag to be of the size specified by the width and height. The [https://github.com/wesnoth/wesnoth/blob/9bd7614e89269b5456ee51ade3cc0af73efc99f5/data/gui/macros/_initial.cfg#L246 GUI_FORCE_WIDGET_SIZE] internal macro is a wrapper around this component.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#int|int]]
| -
| The width the enclosed widget should be forced to (mandatory).
|-
| height
| [[GUIVariable#int|int]]
| -
| The height the enclosed widget should be forced to (mandatory).
|}

Note: Both <code>width</code> and <code>height</code> are mandatory even if you want to fix either width or height as of 1.19.23.

=== Subtag [widget] ===
The widget that should be force-sized.

== 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/stringx

2026-03-22T01:16:29Z

Celtic Minstrel: Note that ipairs works too

{{DevFeature1.15|3}}

The <tt>stringx</tt> module contains additional string support functions. It also registers itself as the string metatable so that these functions can be called directly on strings.

In addition, it permits extracting characters from a string by indexing with an integer. Basically, <syntaxhighlight lang=lua inline>str[n]</syntaxhighlight> is a shorthand for <syntaxhighlight lang=lua inline>str:sub(n,n)</syntaxhighlight>. This means negative indices count from the end of the string, and invalid indices output an empty string. It also means you can use <syntaxhighlight lang=lua inline>ipairs(str)</syntaxhighlight> to iterate over the characters of the string.

== Functions ==

=== stringx.split ===

* '''stringx.split'''(''str'', [''separator''] , [''options'']) → ''list of strings''
* ''str'':'''split'''([''separator''] , [''options'']) → ''list of strings''

Splits a string on a separator character, which currently must be a single character and defaults to <syntaxhighlight lang=lua inline>','</syntaxhighlight>. The optional ''options'' table controls how the string is split (beyond the basic option of the separator character). It can contain the following keys:

* '''remove_empty''': If true, empty strings are omitted from the result. If the options table is omitted, this will default to true; otherwise, it will default to false.
* '''strip_spaces''': Spaces surrounding the separator character are stripped. If the options table is omitted, this will default to true; otherwise, it will default to false.
* '''escape''': Specify a single character as the "escape" character. If a separator character is preceded by this character, then it will not be considered for splitting. The escape character is not removed from the result strings. This option is incompatible with the quote options. For example: <syntaxhighlight lang=lua inline>{escape = [[\]]}</syntaxhighlight>
* '''quote''': Specify one or more quote characters. Any separators within the matching instances of the quotes will not be considered for splitting. For example: <syntaxhighlight lang=lua inline>{quote = [['"]]}</syntaxhighlight>
* '''quote_left''', '''quote_right''': As above, but you can separately specify opening and closing versions of each quote. The first left quote will match the first right quote, the second left quote will match the second right quote, and so on. For example: <syntaxhighlight lang=lua inline>{quote_left = '([', quote_right = ')]'</syntaxhighlight>
* '''expand_anim''': If true, expand the progressive string syntax of [[AnimationWML]]. This option is compatible with the quote options, but since the progressive string syntax treats square brackets as special characters, they may not be specified as quote characters with this option.



=== stringx.escaped_split ===

* '''stringx.escaped_split'''(''str'', [''separator'', [''escape'']]) → ''list of strings''
* ''str'':'''escaped_split'''([''separator'', [''escape'']]) → ''list of strings''

A convenient shorthand for specifying the '''escape''' option in '''stringx.split'''. The separator and escape default to <tt>,</tt> and <tt>\</tt> respectively.

=== stringx.quoted_split ===

* '''stringx.quoted_split'''(''str'', [''separator'', [''quotes'', [''quotes'']]]) → ''list of strings''
* ''str'':'''quoted_split'''([''separator'', [''quotes'', [''quotes'']]]) → ''list of strings''

A convenient shorthand for specifying quote options in '''stringx.split'''. If two quote parameters are passed, they are in the order left, right. The separator defaults to <tt>,</tt> and the quotes default to <tt>(</tt> and <tt>)</tt>.

=== stringx.anim_split ===

* '''stringx.anim_split'''(''str'', [''separator'']) → ''list of strings''
* ''str'':'''anim_split'''([''separator'']) → ''list of strings''

A convenient shorthand for specifying the '''expand_anim''' option in '''stringx.split'''. The separator defaults to <tt>,</tt>.

=== stringx.parenthetical_split ===

* '''stringx.parenthetical_split'''(''str'', ''left_parens'', ''right_parens'') → ''list of strings''
* ''str'':'''parenthetical_split'''(''left_parens'', ''right_parens'') → ''list of strings''

Splits a string into parenthesized portions and portions between the parenthesized portions. With multiple parenthesis types, only the toplevel type at a given point participates in the split. The parentheses default to <tt>(</tt> and <tt>)</tt> respectively.



=== stringx.map_split ===

* '''stringx.map_split'''(''str'', [''item separator'', [''key-value separator'', [''options'']]) → ''string map''
* ''str'':'''map_split'''([''item separator'', [''key-value separator'', [''options'']]) → ''string map''

Splits a string into key-value pairs based on the two separators, which currently must each be a single character. The item separator defaults to <tt>,</tt> and the key-value separator defaults to <tt>:</tt>. The options table supports the following keys:

* '''remove_empty''', '''strip_spaces''': Same as in [[#stringx.split|stringx.split]] above.
* '''default''': Used as the value if any item is missing the ''key_value_separator''.



=== stringx.join ===

* '''stringx.join'''(''list of strings'', [''separator'']) → ''string''
* ''separator'':'''join'''(''list of strings'') → ''string''

Joins a list of strings into a single string using the specified separator string. Accepts its arguments in either order. If omitted, the separator defaults to <tt>,</tt>.

=== stringx.join_map ===

* '''stringx.join_map'''(''string map'', [''item separator'', [''key-value separator'']]) → ''string''
* ''item_separator'':'''join_map'''(''string map'', [''key-value separator'']) → ''string''

Joins a map of strings into a single string using the specified separators. Keys will be output in lexicographical order. Accepts its arguments in any order, with the caveat that the ''item separator'' must appear before the ''key-value separator''. If omitted, the item separator defaults to <tt>,</tt> and the key-value separator defaults to <tt>:</tt>.

=== stringx.ends_with ===

{{DevFeature1.19|4}}

* '''stringx.ends_with'''(''string'', ''suffix'') → ''boolean''

Determines whether the string ends with the specified suffix.

=== stringx.starts_with ===

{{DevFeature1.19|4}}

* '''stringx.starts_with'''(''string'', ''prefix'') → ''boolean''

Determines whether the string starts with the specified prefix.

=== stringx.vformat ===

* '''stringx.vformat'''(''format_string'', ''values'') → ''formatted string''
* ''string'':'''vformat'''(''values'') → ''formatted string''

Similar to '''string.format''' but using Wesnoth's variable substitution syntax, and also supporting translatable strings. Any valid WML table can be passed as the values, though typically you will only need key-value pairs. You could also substitute WML variables into a string by passing '''wml.all_variables''' as the second parameter.

This function preserves the translatability of the input format string.

=== stringx.format_conjunct_list ===

* '''stringx.format_conjunct_list'''(''empty'', ''list_of_strings'') → ''formatted string''

Formats a list of usually-translatable strings into a localized list string of the form "A, B, and C". If the list contains no elements, returns ''empty''.

=== stringx.format_disjunct_list ===

* '''stringx.format_disjunct_list'''(''empty'', ''list_of_strings'') → ''formatted string''

Formats a list of usually-translatable strings into a localized list string of the form "A, B, or C". If the list contains no elements, returns ''empty''.

=== stringx.trim ===

* '''stringx.trim'''(''str'') → ''trimmed string''
* ''str'':'''trim'''() → ''trimmed string''

Strips out any leading and trailing whitespace from the string and returns the resulting string.

=== stringx.parse_range ===

* '''stringx.parse_range'''(''range string'') → ''start'', ''end''
* ''range'':'''parse_range'''() → ''start'', ''end''

Parses a range of the form <syntaxhighlight lang=lua inline>"1-5"</syntaxhighlight> and returns the endpoints of the range as two separate values.

=== stringx.iter_range ===

* '''stringx.iter_range'''(''range string'') → ''iterator'' ⇒ ''integer''
* ''range'':'''iter_range'''() → ''iterator'' ⇒ ''integer''

Iterate over a range of the form <syntaxhighlight lang=lua inline>"1-5"</syntaxhighlight>.

<syntaxhighlight lang=lua>
for i in stringx.iter_range "1-3" do
print(i)
end
-- Output:
-- 1
-- 2
-- 3
</syntaxhighlight>

=== stringx.iter_ranges ===

* '''stringx.iter_ranges'''(''range strings'') → ''iterator'' ⇒ ''integer''
* ''ranges'':'''iter_ranges'''() → ''iterator'' ⇒ ''integer''

Iterates over a sequence of comma-separated ranges. If the ranges overlap, numbers will be yielded more than once.

<syntaxhighlight lang=lua>
for i in stringx.iter_ranges "1-3,7-9" do
print(i)
end
-- Output:
-- 1
-- 2
-- 3
-- 7
-- 8
-- 9
for i in stringx.iter_ranges "1-3,3-6" do
print(i)
end
-- Output:
-- 1
-- 2
-- 3
-- 3
-- 4
-- 5
-- 6
</syntaxhighlight>

[[Category:Lua Reference]]

GrammarWML

2026-03-19T07:45:09Z

Celtic Minstrel: /* Progressive Values */ Add new section covering AnimationWML's progressive values

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

GrammarWML

2026-03-19T07:26:04Z

Celtic Minstrel: Simplify a few very basic productions with special symbols

GrammarWML

2026-03-19T07:19:56Z

Celtic Minstrel: Summarize EBNF syntax at the top of the page, including the special extended syntax I'm using.

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

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
</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 = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
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} , ']' ; (* as is 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 = lowercase | uppercase | 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 = lowercase | uppercase | '_' ; (* 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
hexdigit = digit | 'a' | 'A' | 'b' | 'B' | 'c' | 'C' | 'd' | 'D' | 'e' | 'E' | 'f' | 'F' ;
name_char = lower | upper | digit | '_'
</syntaxhighlight>

[[Category:WML Reference]]

GrammarWML

2026-03-19T07:11:29Z

Celtic Minstrel: /* Help Markup */ Add a new section describing Help markup

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

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
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 = lowercase | uppercase | digit | '_' ; (* Unsure on this, need to check it *)
alternative = {terminal} ;
terminal = '{' , symbol , '}' | '{!}' | '{(}' | '{)}' | (?any unicode character? - '}') ;
</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 = char - '#' ;
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 = lowercase | uppercase | '_' ; (* 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 = char - ("'" | "[") ;
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 = ?any unicode character? - ('<' , '&' , '\') ;
escape = '\' , ?any unicode character? ;
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 = {?any unicode character? - ("'" | '"' | ?space?)} (* Unquoted value *)
| "'" , text - "'" , "'"
| '"' , text - '"' , '"'
;
name = name_char , {name_char} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
hexdigit = digit | 'a' | 'A' | 'b' | 'B' | 'c' | 'C' | 'd' | 'D' | 'e' | 'E' | 'f' | 'F' ;
name_char = lower | upper | digit | '_'
</syntaxhighlight>

[[Category:WML Reference]]

GrammarWML

2026-03-19T06:57:33Z

Celtic Minstrel: /* Context-free Grammars */ Add new section covering Context-free grammar

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

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
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 = lowercase | uppercase | digit | '_' ; (* Unsure on this, need to check it *)
alternative = {terminal} ;
terminal = '{' , symbol , '}' | '{!}' | '{(}' | '{)}' | (?any unicode character? - '}') ;
</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 = char - '#' ;
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 = lowercase | uppercase | '_' ; (* 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 = char - ("'" | "[") ;
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>

[[Category:WML Reference]]

GrammarWML

2026-03-19T06:38:12Z

Celtic Minstrel: Remove "Under Construction" note

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

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
wml_formula = '$' , '(' , wfl_document , ')' ;
</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 = char - '#' ;
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 = lowercase | uppercase | '_' ; (* 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 = char - ("'" | "[") ;
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>

[[Category:WML Reference]]

GrammarWML

2026-03-19T06:37:52Z

Celtic Minstrel: /* Wesnoth Formula Language */ Rewrite in EBNF

----

'''Note:''' This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

----

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

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
wml_formula = '$' , '(' , wfl_document , ')' ;
</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 = char - '#' ;
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 = lowercase | uppercase | '_' ; (* 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 = char - ("'" | "[") ;
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>

[[Category:WML Reference]]

GrammarWML

2026-03-19T06:17:19Z

Celtic Minstrel: Update opening blurb

----

'''Note:''' This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

----

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

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
wml_formula = '$' , '(' , wfl_document , ')' ;
</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.

wfl_comment := '#' [^#]* '#'
wfl_file_run := 'wfl' wfl_string «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
wfl_formula := 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_opt? (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 := [a-zA-Z_]+
wfl_number := [0-9]+ ('.' [0-9]+)?
wfl_string := "'" ([^'[]+ | wfl_string_subst | wfl_string_escape)* "'"
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 := wfl_formula '->' wfl_formula (',' wfl_formula '->' wfl_formula)*
wfl_function_call := wfl_name '(' wfl_expression_list? ')'

[[Category:WML Reference]]

GrammarWML

2026-03-19T06:10:30Z

Celtic Minstrel: /* WML Substitutions */ Rewrite in EBNF

----

'''Note:''' This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

----

{{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 regular-expression-like (which is not quite the same as regex-like!), with the following conventions:

* Literal values are enclosed in either 'single quotes' or "double quotes".
* Square brackets enclose character classes, with initial ^ inverting them
* Whitespace within an expression (unless quoted) is used only for readability or to separate non-terminals
* The meta-characters * + ? | have the same meaning as is typical in regular expressions
* The sequence «tab» represents a tab character, and «nl» represents an end-of-line character or character sequence
* Multiple definitions of a non-terminal are equivalent to alternation (ie, x:=4 and x:=7 combine to produce x:=4|7)

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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} , ']' ; (* as is digit *)
wml_var_default = '?' , default_char, {default_char} , '|' ;
default_char = char - '|' ;
wml_formula = '$' , '(' , wfl_document , ')' ;
</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.

wfl_comment := '#' [^#]* '#'
wfl_file_run := 'wfl' wfl_string «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
wfl_formula := 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_opt? (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 := [a-zA-Z_]+
wfl_number := [0-9]+ ('.' [0-9]+)?
wfl_string := "'" ([^'[]+ | wfl_string_subst | wfl_string_escape)* "'"
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 := wfl_formula '->' wfl_formula (',' wfl_formula '->' wfl_formula)*
wfl_function_call := wfl_name '(' wfl_expression_list? ')'

[[Category:WML Reference]]

GrammarWML

2026-03-19T06:03:31Z

Celtic Minstrel: /* WML */ Rewrite in EBNF

----

'''Note:''' This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

----

{{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 regular-expression-like (which is not quite the same as regex-like!), with the following conventions:

* Literal values are enclosed in either 'single quotes' or "double quotes".
* Square brackets enclose character classes, with initial ^ inverting them
* Whitespace within an expression (unless quoted) is used only for readability or to separate non-terminals
* The meta-characters * + ? | have the same meaning as is typical in regular expressions
* The sequence «tab» represents a tab character, and «nl» represents an end-of-line character or character sequence
* Multiple definitions of a non-terminal are equivalent to alternation (ie, x:=4 and x:=7 combine to produce x:=4|7)

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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 = {char - '+' | '"' | ?newline?} ;
string = '"' . {char - '"' | '""'} , '"' ;
raw_string = '<<' , {char - '>' | '>' , char - '>'} , '>>' ;
textdomain = '#textdomain' domain_char , {domain_char} , ?newline? ;
wml_id_char = lowercase | uppercase | digit | '_' ;
lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
| 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' ;
uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
| 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
domain_char = wml_id_char | '-' ;
char = ?any unicode character? ;
</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.

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 := [a-zA-Z0-9_]+
wml_var_index := '[' [0-9]+ ']'
wml_var_default := '?' [^|]+ '|'
wml_formula := '$' '(' wfl_document ')'

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

wfl_comment := '#' [^#]* '#'
wfl_file_run := 'wfl' wfl_string «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
wfl_formula := 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_opt? (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 := [a-zA-Z_]+
wfl_number := [0-9]+ ('.' [0-9]+)?
wfl_string := "'" ([^'[]+ | wfl_string_subst | wfl_string_escape)* "'"
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 := wfl_formula '->' wfl_formula (',' wfl_formula '->' wfl_formula)*
wfl_function_call := wfl_name '(' wfl_expression_list? ')'

[[Category:WML Reference]]

GrammarWML

2026-03-19T05:49:48Z

Celtic Minstrel: /* WML Preprocessor */ Rewrite in EBNF

----

'''Note:''' This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

----

{{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 regular-expression-like (which is not quite the same as regex-like!), with the following conventions:

* Literal values are enclosed in either 'single quotes' or "double quotes".
* Square brackets enclose character classes, with initial ^ inverting them
* Whitespace within an expression (unless quoted) is used only for readability or to separate non-terminals
* The meta-characters * + ? | have the same meaning as is typical in regular expressions
* The sequence «tab» represents a tab character, and «nl» represents an end-of-line character or character sequence
* Multiple definitions of a non-terminal are equivalent to alternation (ie, x:=4 and x:=7 combine to produce x:=4|7)

== 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} ;
digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;
char = ?any unicode character? ;
</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.

wml_doc := (wml_tag | wml_attribute)*
wml_tag := '[' '+'? wml_name ']' wml_doc '[/' wml_name ']'
wml_name := [a-zA-Z0-9_]+
wml_attribute := textdomain? wml_key_sequence '=' wml_value «nl»
wml_key_sequence := wml_name (',' wml_name)*
wml_value := wml_value_component ('+' («nl» textdomain?)? wml_value_component)*
wml_value_component := text | '_'? string | '_'? raw_string

text := [^+«nl»"]*
string := '"' ([^"] | '""')* '"'
raw_string := '<<' ([^>] | >[^>])* '>>'
textdomain := '#textdomain' [a-zA-Z0-9_-]+ «nl»

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

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 := [a-zA-Z0-9_]+
wml_var_index := '[' [0-9]+ ']'
wml_var_default := '?' [^|]+ '|'
wml_formula := '$' '(' wfl_document ')'

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

wfl_comment := '#' [^#]* '#'
wfl_file_run := 'wfl' wfl_string «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
wfl_formula := 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_opt? (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 := [a-zA-Z_]+
wfl_number := [0-9]+ ('.' [0-9]+)?
wfl_string := "'" ([^'[]+ | wfl_string_subst | wfl_string_escape)* "'"
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 := wfl_formula '->' wfl_formula (',' wfl_formula '->' wfl_formula)*
wfl_function_call := wfl_name '(' wfl_expression_list? ')'

[[Category:WML Reference]]

GrammarWML

2026-03-19T04:37:18Z

Celtic Minstrel: Add an "under construction" notice

----

'''Note:''' This page is currently undergoing reconstruction. Information on the page may become misleading or occasionally wrong for brief periods of time.

----

{{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 regular-expression-like (which is not quite the same as regex-like!), with the following conventions:

* Literal values are enclosed in either 'single quotes' or "double quotes".
* Square brackets enclose character classes, with initial ^ inverting them
* Whitespace within an expression (unless quoted) is used only for readability or to separate non-terminals
* The meta-characters * + ? | have the same meaning as is typical in regular expressions
* The sequence «tab» represents a tab character, and «nl» represents an end-of-line character or character sequence
* Multiple definitions of a non-terminal are equivalent to alternation (ie, x:=4 and x:=7 combine to produce x:=4|7)

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

preproc_doc := (preproc_directive | preproc_line)*
preproc_directive := simple_directive | macro_definition | if_block
preproc_line := (preproc_text | '<<' macro_free_text '>>' | macro_inclusion)* comment? «nl»
preproc_text := (preproc_char | '<' preproc_char)* '<'?
preproc_char := [^<{#«nl»]
macro_free_text := (macro_free_char | '>' macro_free_char)*
macro_free_char := [^>]
macro_inclusion := '{' ([^}]+ | macro_function) '}'
macro_function := macro_name_char+ (macro_argument)*
macro_name_char := [^} «tab»]
macro_argument := (macro_name_char | macro_inclusion)+
macro_argument := '(' preproc_doc? ')' | '_'? '"' ([^}"]
macro_argument := ('""' | macro_inclusion)* '"'
macro_argument := '<<' macro_free_text '>>'
comment := '#' [^«nl»]+ «nl»
ws := ' ' | «tab»
simple_directive := '#undef' ws+ macro_name_char+ ws* «nl»
simple_directive := ('#warning' | '#error') ws+ [^«nl»]* «nl»
macro_definition := '#define' ws+ macro_name_char+ (ws+ macro_name_char+)* «nl» (opt_arg_definition)* (simple_directive | if_block | preproc_line)+ '#enddef' «nl»
opt_arg_definition := '#arg' ws+ macro_name_char+ «nl» (simple_directive | if_block | preproc_line)+ '#endarg' «nl»
if_block := (ifdef_header | ifver_header | ifhave_header) «nl» preproc_doc ('#else' «nl» preproc_doc)? '#endif' «nl»
ifdef_header := ('#ifdef' | '#ifndef') ws+ macro_name_char+
ifver_header := ('#ifver' | '#ifnver') ws+ macro_name_char+ ws* comparison_op ws* version_string
ifhave_header := ('#ifhave' | '#ifnhave') ws+ [^«nl»]+
comparison_op := '<' | '<=' | '==' | '!=' | '>=' | '>'
version_string := integer ('.' integer)*
integer := [0-9]+

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

wml_doc := (wml_tag | wml_attribute)*
wml_tag := '[' '+'? wml_name ']' wml_doc '[/' wml_name ']'
wml_name := [a-zA-Z0-9_]+
wml_attribute := textdomain? wml_key_sequence '=' wml_value «nl»
wml_key_sequence := wml_name (',' wml_name)*
wml_value := wml_value_component ('+' («nl» textdomain?)? wml_value_component)*
wml_value_component := text | '_'? string | '_'? raw_string

text := [^+«nl»"]*
string := '"' ([^"] | '""')* '"'
raw_string := '<<' ([^>] | >[^>])* '>>'
textdomain := '#textdomain' [a-zA-Z0-9_-]+ «nl»

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

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 := [a-zA-Z0-9_]+
wml_var_index := '[' [0-9]+ ']'
wml_var_default := '?' [^|]+ '|'
wml_formula := '$' '(' wfl_document ')'

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

wfl_comment := '#' [^#]* '#'
wfl_file_run := 'wfl' wfl_string «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
wfl_formula := 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_opt? (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 := [a-zA-Z_]+
wfl_number := [0-9]+ ('.' [0-9]+)?
wfl_string := "'" ([^'[]+ | wfl_string_subst | wfl_string_escape)* "'"
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 := wfl_formula '->' wfl_formula (',' wfl_formula '->' wfl_formula)*
wfl_function_call := wfl_name '(' wfl_expression_list? ')'

[[Category:WML Reference]]

Download/zh-Hans

2026-03-02T13:00:54Z

Celtic Minstrel: Update version numbers and delete some obsolete information (references to MacCompileStuff, Download_Xdeltas, Eclipse plugin) -- I'm not sure how accurate the rest of this info is, but I doubt the core of this page changes THAT drastically over time

{{Translations}}
欢迎来到韦诺之战下载页。韦诺之战项目团队官方发布源代码及适用于Windows、OS X、OpenPandora和多种Linux发行版的二进制构建版本。BT种子是非官方的。

如果适用于您的操作系统的最新的二进制可执行文件尚未提供，请过几天再来此处查看是否已提供。打包者们已被告知本次发布的相关情况，请保持耐心。在此期间，请阅读[[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|常见问题]]。

韦诺之战也在[http://brew.sh/ Homebrew]以及[http://www.macports.org/ Macports]上提供。Macports上只有稳定版本。Homebrew 上有稳定发布版，开发发布版，同时也会构建最“前沿”的主开发分支。
__NOTOC__
== 稳定版（1.18 分支） ==
稳定版是希望作为稳定且平衡的游戏版本来使用。1.19分支的每一个版本都相互兼容。

版本1.18.6是最新的稳定版。这个版本推荐给绝大多数玩家，因为1.18在线多人游戏社区很庞大，而且用户自制战役服务器上也有很好的内容可供选择。

==== 源代码 ====
* [[CompilingWesnoth|编译指导]] - 如何编译源代码
{{StableDownload|当前版本|先前版本|当前源代码包的md5sum值|微软视窗操作系统|麦金塔操作系统}}

==== GNU/Linux ====
* 有许多二进制文件对应于不同的Linux发行版。不是所有的文件都已及时更新到最新版。请查阅[[WesnothBinariesLinux|Linux二进制文件页]]寻找对应于你的发行版的二进制包信息。

==== 杂项 ====
* [http://sourceforge.net/projects/wesnoth/files/ 当前和所有先前版本的SourceForge页]


== 许可 ==
'''主要文章：[[Wesnoth:Copyrights|版权声明]]

本程序为自由软件；您可依据[http://www.fsf.org Free Software Foundation|自由软件基金会]所发表的[http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2|GNU通用公共许可证第2版]条款规定，就本程序再为发布与／或修改。
本程序是基于使用目的而加以发布，然而不负任何担保责任；亦无对适售性或特定目的适用性所为的默示性担保。详情请参照GNU通用公共授权。

== 参见 ==
* [http://changelog.wesnoth.org 更新日志]
* [[WesnothRepository]] - 版本库中最前沿的版本

[[Category:Building and Installing]]

Download/ukr

2026-03-02T12:59:28Z

{{Translations}}
Ласкаво просимо на сторінку завантаження «Битви за Веснот». Команда проекту BfW офіційно постачає джерельний код та бінарні пакети для Windows, OS X, OpenPandora, та різних дистрибутивів Linux. Торренти є неофіційними.

Якщо виконувані файли останньої версії гри для вашої ОС ще не доступні, то, можливо, вони з'являться на цій сторінці через деякий час. Спробуйте перевірити через кілька днів. Люди, що займаються зборкою, знають про реліз, тому, будь ласка, запасіться терпінням. Тим часом, можете прочитати [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

Wesnoth також доступний для OS X від [http://brew.sh/ Homebrew] і [http://www.macports.org/ MacPorts]. В MacPorts є тільки стабільна версія. В Homebrew є стабільний та розробницький релізи.

__NOTOC__
Перейти до: [[Download/ua#Стабільні_версії_.28гілка_1.10.29|Стабільна гілка]] | [[Download/ua#Розробка_.28гілка_1.11.29|Гілка розробки]]

== Стабільні версії (гілка 1.18) ==
Стабільні файли пропонується використовувати в тому випадку, якщо потрібна стабільна і одночасно збалансована версія гри. Всі версії гілки 1.18 сумісні одина з одною.

Версія 1.10.7 на даний момент є попередньою стабільною версією. Ця версія рекомендується для більшості гравців, оскільки в багатокористувацькій грі співтовариство 1.10 дуже велике і створений користувачами сервер кампаній пропонує багатий вибір контенту.

==== Джерельний код ====
* [[CompilingWesnoth|Керівництво з компіляції]] - як зкомпілювати джерельний код.
{{StableDownload|Поточна версія|Попередня версія|md5sum джерельних кодів поточної версії}}

==== GNU/Linux ====
* Існують пакети для безлічі різних дистрибутивів GNU / Linux. Не всі з них оновлюються з виходом нового релізу гри. Будь ласка, ознайомтеся з [[WesnothBinariesLinux|Сторінка збірок для Linux]] для того, щоб дізнатися більше про збірки для вашого дистрибутива.

==== Додатково ====
* [http://sourceforge.net/projects/wesnoth/files/ Сторінка на SourceForge дпоточної та всіх попередніх версій]


== Ліцензія ==
''Головна стаття: [[Wesnoth:Copyrights]]

Ця програма є вільним програмним забезпеченням; ви можете розповсюджувати та / або змінювати його відповідно до умов [http://www.fsf.org/copyleft/gpl.html GNU General Public License версії 2], опублікованій на сайті [http://www.fsf.org Free Software Foundation].
Ця програма поширюється в надії, що вона буде корисна, але без будь-якої гарантії; навіть без гарантій щодо товарного стану й придатності для конкретної мети. Дивіться GNU General Public License для більш докладної інформації.

== Дивіться також ==
* [http://changelog.wesnoth.org Список змін]
* [[WesnothRepository]] - найновіша версія з репозиторію

[[Category:Building and Installing]]

Download/ru

2026-03-02T12:58:35Z

{{Translations}}
Добро пожаловать на страницу загрузки «Битвы за Веснот». Команда проекта BFW официально поставляет только исходный код, бинарные пакеты же предоставлены добровольцами сообщества и размещаются на этой странице. Торренты тоже официально не поддерживаются.

Если сборки последней версии игры для вашей ОС еще не доступны, то, возможно, они появятся на этой странице спустя какое-то время. Попробуйте проверить через несколько дней. Люди, занимающиеся сборкой, знают о релизе, поэтому, пожалуйста, запаситесь терпением. А тем временем можете прочесть [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__

== Стабильные версии (ветка 1.18) ==
Стабильные файлы предлагается использовать в том случае, если нужна стабильная и одновременно сбалансированная версия игры. Все версии ветки 1.18 совместимы друг с другом.

Версия 1.18.1 на данный момент является последней стабильной версией. Эта версия рекомендуется для большинства игроков, поскольку в многопользовательской игре сообщество 1.18 очень большое и созданный пользователями сервер кампаний предлагает богатый выбор контента.

==== Исходный код ====
* [[CompilingWesnoth|Гайд по компилированию]] - как откомпилировать исходный код
{{StableDownload|Текущая версия|Предыдущая версия|md5sum для исходников текущей версии}}

==== GNU/Linux ====
* Существуют пакеты для множества различных дистрибутивов GNU/Linux. Не все из них обновляются с выходом нового релиза игры. Пожалуйста, ознакомьтесь с [[WesnothBinariesLinux|Страница сборок для Linux]] для того, чтобы узнать больше информации о сборках для вашего дистрибутива.

==== Дополнительно ====
* [http://sourceforge.net/projects/wesnoth/files/ Страница на SourceForge для текущей и всех предыдущих версий]

== Лицензия ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== Смотрите также ==
* [http://changelog.wesnoth.org Список изменений]
* [[WesnothRepository]] - новейшая версия из репозитория

[[Category:Building and Installing]]

Download/fr

2026-03-02T12:57:11Z

Celtic Minstrel: Delete some obsolete information (references to MacCompileStuff, Download_Xdeltas, Eclipse plugin) -- I'm not sure how accurate the rest of this info is, but I doubt the core of this page changes THAT drastically over time

{{Translations}}
''Traduction en cours''

''Atention : la version anglaise de cette page est la plus fiable''

Bienvenue sur la page de téléchargement de ''La bataille pour Wesnoth''. L'équipe du projet publie officiellement le code source et les paquets binaires pour Windows, macOs, et différentes distributions GNU/Linux.

Si les derniers binaire ne sont pas disponible pour votre système d'exploitation, vous pouvez venir vérifier dans quelques jours si ce n'est toujours pas le cas. Les mainteneurs des paquets sont au courant des sorties, merci d'être patient. En attendant, vous pouvez lire la [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS_X.2C_etc..5D.3F|FAQ (en)]].

La bataille pour Wesnoth est également disponible pour OS X chez [http://brew.sh/ Homebrew] et [http://www.macports.org/ Macports]. Chez Macports, il n'y a que la version stable. Chez Homebrew vous pouvez trouver la branche stable et celle de développement, vous pouvez aussi compiler la branche principale "bleeding edge" depuis le [[WesnothRepository|dépôt Git(en)]].
__NOTOC__
== Branche Stable ==
Cette version est conseillée à la plupart des joueurs puisqu'elle offre une expérience de jeu la plus testée et équilibrée, et n'a que peu de mises à jour de correction de bugs. Chaque version de la branche stable sont compatibles entres elles. La communauté de joueurs en ligne est aussi la plus importante et le serveur d'extensions dispose d'un vaste choix de jeux suplémentaires.

====Code source ====
* [[CompilingWesnoth|Compiling Guide]] - Comment compiler le code source en anglais.
{{StableDownload}}

==== GNU/Linux ====
*Il existe des paquets binaires pour plusieurs distributions différentes. Il ne sont pas toujours à jour avec les versions en vigueur. Vous pouvez lire la page [[WesnothBinariesLinux|Linux binary page]] pour plus d'information sur les paquets correspondant à votre distribution.

==== Divers ====
* [[Download_Xdeltas#Stable_Version_1.14.x|Xdelta for the source code]]
* [https://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]



== License ==
''Page principale: [[Wesnoth:Copyrights]]''

Ce programme est un logiciel libre; vous pouvez le distribuer et/ou le modifier selon les termes de la licence
[https://www.gnu.org/licenses/gpl-2.0.html GNU General Public License version 2], comme publiée par la [https://www.fsf.org Free Software Foundation], ou choisir une version plus récente.

Ce programme est proposé en espérant qu'il sera utile, mais sans garantie; sans même la garantie commerciale ou une garantie de conformité. Allez voir La licence publique générale GNU pour plus de détails.

Certaines ressources du jeu sont fournies selon les termes de la licence [https://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 license].

== Voir aussi ==
* [https://changelog.wesnoth.org/1.14 Changelog for the stable version]
* [https://changelog.wesnoth.org Changelog for the development version]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download/de

2026-03-02T12:55:58Z

Celtic Minstrel: Delete obsolete link to Download_Xdeltas

{{Translations}}
Willkommen auf der Battle for Wesnoth-Downloadseite. Das BfW-Team veröffentlicht offiziell nur den Quelltext. Binärpakete werden nur von Freiwilligen aus der Gemeinschaft zur Verfügung gestellt und hier angeboten.

Wenn die neuesten Binärpakete für dein Betriebssystem momentan noch nicht verfügbar sind, überprüfe einfach alle paar Tage ob du sie hier finden kannst. Die jeweilig Verantwortlichen wurden informiert, bitte habe etwas Geduld. In der Zwischenzeit kannst du die [[/FAQ/de#Eine_neue_Version_wurde_ver.C3.B6ffentlicht.2C_aber_wo_kann_man_die_.5BWindows.2C_Mac_OS_X.2C_usw..5D-Version_herunterladen.3F|FAQ-Seite]] lesen.
__NOTOC__
Springen zu: [[Download/de#Hauptversion (1.18-Zweig)|Hauptversion]] | [[Download/de#Entwicklungsversion (1.19-Zweig)|Entwicklungsversion]]

== Hauptversion (1.18-Zweig) ==
Die Hauptversion ist eine stabile und ziemlich ausgewogene Version des Spiels. Alle Versionen des 1.18-Zweigs sind miteinander kompatibel.

==== Quelltext ====
* [[CompilingWesnoth|Kompilierungsanleitung]] - wie man den Quelltext kompiliert
{{StableDownload|Neueste Version|Vorherige Version|md5sum für den aktuellen Quelltext}}

==== GNU/Linux ====
* Es gibt Binärpakete für viele verschiedene GNU/Linux-Distributionen. Nicht alle sind immer auf dem Stand der neuesten Version. Für mehr Informationen über die Binärpakete für deine Distribution lies bitte die [[WesnothBinariesLinux|entsprechende Seite]].

==== Verschiedenes ====
* [http://web.archive.org/web/20200412113411/https://wiki.wesnoth.org/Download_Xdeltas#Stable_Version_1.18.x Xdelta für den Quelltext]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge-Seite für die aktuellen und alle vorherigen Versionen]

== Entwicklungsversion (1.19-Zweig) ==
Version 1.19.x ist die neueste Entwicklungsversion, die verbesserte Grafik und neue aufregende Inhalte vorstellt. Allerdigs können auch Programmierfehler oder andere Probleme auftreten, da schwerwiegende Änderungen stattfinden.

Um ausgewogen und stabil zu spielen solltest du die neueste Version des 1.18-Zweigs benutzen. Diese Version hingegen ist Programmierern und Kampagnenentwicklern zu empfehlen, ebenso wie denen, die wissen wollen, wie Wesnoth zukünftig aussehen wird.

Wer mit Versionskontrolle und Kompilierung vertraut ist, kann der aktuellen Entwicklung durch das Überprüfen von [[WesnothRepository]] folgen.

==== Quelltext ====
* [[CompilingWesnoth|Kompilierungsanleitung]] - wie man den Quellext kompiliert
{{DevDownload|Neueste Version|Vorherige Version|md5sum für den aktuellen Quelltext}}

==== GNU/Linux ====
* Es gibt Binärpakete für viele verschiedene GNU/Linux-Distributionen. Nicht alle sind immer auf dem Stand der neuesten Version. Für mehr Informationen über die Binärpakete für deine Distribution lies bitte die [[WesnothBinariesLinux|entsprechende Seite]].

==== Verschiedenes ====
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge-Seite für die aktuelle und alle vorherigen Versionen]

== Lizenz ==
''Hauptartikel: [[Wesnoth:Copyrights]]

Dieses Programm ist freie Software; du kannst es weitervertreiben und/oder modifizieren, solange das unter den Bedingungen der [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2] bleibt, veröffentlicht von der [http://www.fsf.org Free Software Foundation].
Dieses Programm wird mit der Hoffnung vertrieben, dass es nützlich ist, allerdings ohne Garantie; ohne die auch nur angedeutete Garantie auf Marktgängigkeit oder Eignung für eine bestimmte Absicht. Siehe die GNU Allgemeine Öffentliche Lizenz für mehr Informationen.

== Siehe auch ==
* [http://changelog.wesnoth.org Versionshistorie]
* [[WesnothRepository]] - bleeding-edge-Version von Quelle

[[Category:Building and Installing]]

Download/es

2026-03-02T12:55:30Z

{{Translations}} __NOTOC__
Bienvenidos a la página de descargas de ''La Batalla por Wesnoth''. El equipo de ''La Batalla por Wesnoth'' sólo publica de forma oficial el código fuente y paquetes para Windows, macOS y varias distribuciones de Linux.

Si la última versión de los binarios no está disponible para tu sistema operativo, por favor vuelve a comprobar en unos días si ya lo está. Se ha informado convenientemente a los empaquetadores, así que debes ser paciente. Durante la espera puedes leer las [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS_X.2C_etc..5D.3F | preguntas frecuentes]] a este respecto.

== Estable (serie 1.18) ==
<b>1.18.x</b> es la serie estable actual. Éstas publicaciones son recomendadas para la mayoría de los jugadores, ya que proporcionan una experiencia de juego probada y balanceada con actualizaciones ocasionales con parches de defectos. Cada versión en esta serie es compatible con las otras. La comunidad en línea de jugadores para esta serie también es la más grande y el servidor de complementos tiene una vasta selección de contenido.

==== Código fuente ====
* [[CompilingWesnoth|Guía de compilación]] - cómo compilar el código fuente
{{StableDownload|Versión actual|Versión anterior}}

==== GNU/Linux ====
* Existen binarios para muchas distribuciones diferentes de GNU/Linux. No siempre están todos actualizados a la última publicación. Por favor, echa un vistazo a la [[WesnothBinariesLinux | página de binarios para Linux]] para obtener más información sobre los binarios para tu distribución.

==== Miscelánea ====
* [[Download_Xdeltas#Stable_Version_1.18.x|Xdelta para el código fuente]]
* [https://sourceforge.net/projects/wesnoth/files/ Página de SourceForge para la versión actual y todas las anteriores]

== Desarrollo (serie 1.19) ==
<b>1.19.x</b> es la serie de desarrollo actual, presentando nuevas y emocionantes características. Sin embargo, es posible que presente defectos o problemas de rendimiento en ocasiones. Creadores de contenido, desarrolladores y jugadores que deseen darle un vistazo al futuro de Wesnoth podrían estar interesados en probar esta serie.

Aquellos que estén familiarizados con el uso de sistemas de control de versiones y compilar el juego a partir de su código fuente pueden seguir de más cerca aún el desarrollo de Wesnoth usando el [[WesnothRepository|repositorio Git]] en vez de las publicaciones de esta serie.

==== Código fuente ====
* [[CompilingWesnoth | Guía de compilación]] - cómo compilar el código fuente
{{DevDownload|Versión actual|Versión anterior}}

==== GNU/Linux ====
* Existen binarios para muchas distribuciones diferentes de GNU/Linux. No siempre están todos actualizados a la última publicación. Por favor, echa un vistazo a la [[WesnothBinariesLinux | página de binarios para Linux]] para obtener más información sobre los binarios para tu distribución.

==== Miscelánea ====
* [https://sourceforge.net/projects/wesnoth/files/ Página de SourceForge para la versión actual y todas las anteriores]

== Licencia ==
''Artículo principal: [[Wesnoth:Copyrights]]''

Este programa es software libre; puedes redistribuirlo o modificarlo bajo los términos de la [https://www.gnu.org/licenses/gpl-2.0.html GNU General Public License, versión 2], publicada por la [https://www.fsf.org Free Software Foundation]. Este programa se distribuye con la esperanza de que sea útil, pero sin ninguna garantía; incluso sin la garantía implícita de comerciabilidad o aptitud para un propósito particular. Vea la Licencia Pública General de GNU para más detalles.

== Véase también ==
* [http://changelog.wesnoth.org Registro de cambios]
* [[WesnothRepository | Repositorio de Wesnoth]] - Obtener la última versión desde el repositorio

[[Category:Building and Installing]]

Download/de

2026-03-02T12:53:06Z

Celtic Minstrel: Update version numbers and delete some obsolete information (references to MacCompileStuff and the Eclipse plugin) -- I'm not sure how accurate the rest of this info is, but I doubt the core of this page changes THAT drastically over time

{{Translations}}
Willkommen auf der Battle for Wesnoth-Downloadseite. Das BfW-Team veröffentlicht offiziell nur den Quelltext. Binärpakete werden nur von Freiwilligen aus der Gemeinschaft zur Verfügung gestellt und hier angeboten.

Wenn die neuesten Binärpakete für dein Betriebssystem momentan noch nicht verfügbar sind, überprüfe einfach alle paar Tage ob du sie hier finden kannst. Die jeweilig Verantwortlichen wurden informiert, bitte habe etwas Geduld. In der Zwischenzeit kannst du die [[/FAQ/de#Eine_neue_Version_wurde_ver.C3.B6ffentlicht.2C_aber_wo_kann_man_die_.5BWindows.2C_Mac_OS_X.2C_usw..5D-Version_herunterladen.3F|FAQ-Seite]] lesen.
__NOTOC__
Springen zu: [[Download/de#Hauptversion (1.18-Zweig)|Hauptversion]] | [[Download/de#Entwicklungsversion (1.19-Zweig)|Entwicklungsversion]]

== Hauptversion (1.18-Zweig) ==
Die Hauptversion ist eine stabile und ziemlich ausgewogene Version des Spiels. Alle Versionen des 1.18-Zweigs sind miteinander kompatibel.

==== Quelltext ====
* [[CompilingWesnoth|Kompilierungsanleitung]] - wie man den Quelltext kompiliert
{{StableDownload|Neueste Version|Vorherige Version|md5sum für den aktuellen Quelltext}}

==== GNU/Linux ====
* Es gibt Binärpakete für viele verschiedene GNU/Linux-Distributionen. Nicht alle sind immer auf dem Stand der neuesten Version. Für mehr Informationen über die Binärpakete für deine Distribution lies bitte die [[WesnothBinariesLinux|entsprechende Seite]].

==== Verschiedenes ====
* [http://web.archive.org/web/20200412113411/https://wiki.wesnoth.org/Download_Xdeltas#Stable_Version_1.18.x Xdelta für den Quelltext]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge-Seite für die aktuellen und alle vorherigen Versionen]

== Entwicklungsversion (1.19-Zweig) ==
Version 1.19.x ist die neueste Entwicklungsversion, die verbesserte Grafik und neue aufregende Inhalte vorstellt. Allerdigs können auch Programmierfehler oder andere Probleme auftreten, da schwerwiegende Änderungen stattfinden.

Um ausgewogen und stabil zu spielen solltest du die neueste Version des 1.18-Zweigs benutzen. Diese Version hingegen ist Programmierern und Kampagnenentwicklern zu empfehlen, ebenso wie denen, die wissen wollen, wie Wesnoth zukünftig aussehen wird.

Wer mit Versionskontrolle und Kompilierung vertraut ist, kann der aktuellen Entwicklung durch das Überprüfen von [[WesnothRepository]] folgen.

==== Quelltext ====
* [[CompilingWesnoth|Kompilierungsanleitung]] - wie man den Quellext kompiliert
{{DevDownload|Neueste Version|Vorherige Version|md5sum für den aktuellen Quelltext}}

==== GNU/Linux ====
* Es gibt Binärpakete für viele verschiedene GNU/Linux-Distributionen. Nicht alle sind immer auf dem Stand der neuesten Version. Für mehr Informationen über die Binärpakete für deine Distribution lies bitte die [[WesnothBinariesLinux|entsprechende Seite]].

==== Verschiedenes ====
* [http://web.archive.org/web/20200412113411/https://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.19.x Xdelta für den Quelltext]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge-Seite für die aktuelle und alle vorherigen Versionen]

== Lizenz ==
''Hauptartikel: [[Wesnoth:Copyrights]]

Dieses Programm ist freie Software; du kannst es weitervertreiben und/oder modifizieren, solange das unter den Bedingungen der [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2] bleibt, veröffentlicht von der [http://www.fsf.org Free Software Foundation].
Dieses Programm wird mit der Hoffnung vertrieben, dass es nützlich ist, allerdings ohne Garantie; ohne die auch nur angedeutete Garantie auf Marktgängigkeit oder Eignung für eine bestimmte Absicht. Siehe die GNU Allgemeine Öffentliche Lizenz für mehr Informationen.

== Siehe auch ==
* [http://changelog.wesnoth.org Versionshistorie]
* [[WesnothRepository]] - bleeding-edge-Version von Quelle

[[Category:Building and Installing]]

Download

2026-03-02T12:49:03Z

Celtic Minstrel: Add the translations toolbar

Welcome to the ''Battle for Wesnoth'' downloads page. The BfW project team officially releases the source code and builds for Windows, macOS, and various Linux distributions.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS_X.2C_etc..5D.3F|FAQ]].

{{Translations}}

__NOTOC__
== Stable (1.18 branch) ==
<b>1.18.x</b> is the current stable branch. These releases are recommended for most players, as they provide a well-tested and balanced game experience with only occasional bug-fix updates. Each version of this branch is compatible with each other. The online player community for it is also the largest and the add-ons server has a vast selection of content.
{{StableDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [https://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Development (1.19 branch) ==
<b>1.19.x</b> is the current development branch, boasting new exciting features. However, there may be occasional bugs or performance problems in these releases. Content creators, coders, and players who want to preview the future of Wesnoth may be interested in checking out our work in this branch.

People familiar with version control systems and building the game from source may follow Wesnoth development even more closely using the [[WesnothRepository|Git repository]] instead.
{{DevDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [https://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== License ==
''Main article: [[Wesnoth:Copyrights]]''

This program is free software; you can redistribute it and/or modify it under the terms of the [https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3], as published by the [https://www.fsf.org Free Software Foundation], or at your option, any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

Some assets included with the game are provided under the terms of the [https://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 license].

== See also ==
* [https://changelog.wesnoth.org/1.18 Changelog for the stable version]
* [https://changelog.wesnoth.org Changelog for the development version]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

VariablesWML

2026-02-22T07:03:13Z

Celtic Minstrel: Undo revision 74848 by Sapient (talk) -- Who are we do prescribe what may be done?

{{Template:WML Tags}}
Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign or scenario unless explicitly cleared.
Variable names can contain only alphanumerics and underscores and are case-sensitive. Though technically permitted, it is recommended not to use an underscore as the first character of a variable name.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* [[#Assigning Variables|'''Assigning to a variable''']]: stores a value in the variable, either creating a new variable or modifying a variable that already exists.
* [[#Reading Variables|'''Querying a variable''']]: retrieves the last value stored in the variable (usually returning an empty string if no value was stored).
* [[#Clearing Variables|'''Clearing a variable''']]: makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games.

== Kinds of Variables ==
=== Scalar ===
A scalar variable can store a single string, number, or boolean value.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([[SyntaxWML#Special_Attribute_Values|Special Attribute Values]]).

=== Container ===
A container variable can store any number of scalar variables, as well as nested containers. There are tags to assign specific information, for instance [store_side]. To refer to a variable <code>bar</code> stored in a container <code>foo</code> you would write <code>foo.bar</code>. This works even if one of the variable names is entirely numeric.

=== Array ===
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

Arrays are indexed from 0, which means that if <code>foo</code> is the name of an array, <code>foo[0]</code> is the full name of its first container variable, <code>foo[1]</code> the full name of its second, and so on.

For an array variable, <code>foo.length</code> is the special variable that always stores the number of containers in the array <code>foo</code>. Hence, if the value stored in <code>foo.length</code> is 18, the last container in the array would be <code>foo[17]</code>.

If you try to query an array as if it were a container, then it will simply use the first index. Thus <code>$foo.bar</code> would be the same as <code>$foo[0].bar</code>. An explicit index inside an array is also considered a container.

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <code>foo[3]</code> as if it were a scalar one is illegal; instead, you would use <code>foo[3].value</code> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a save of a game that contains such variables will fail with a WML error.)

=== Global ===

Most WML variables are global variables, and unless they are explicitly cleared, they will continue to exist across all events and scenarios until a campaign ends. Variables created with '''[set_variable]''', '''[set_variables]''', or any of the [store_something] styled WML tags such as '''[store_unit]''' may all used to create or modify global variables. Likewise, [[#Variable Substitution|variable substitution]] and the '''[variable]''' conditional tag may be used to read global variables.

=== Unit ===

Unit variables may be stored on a specific unit in a special '''variables''' child container. That means that, if desired, every unit could have a variable with the same name, and it wouldn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Unit variables can be read after storing a unit then can be created by setting data in the '''variables''' child container and unstoring the unit. A one-step way of creating unit variables is possible with '''[modify_unit]''', but to read the variables you still usually need to use '''[store_unit]'''. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardUnitFilter]] or [[AbilitiesWML]]) and the '''[filter_wml][variables]''' tag in [[StandardUnitFilter]], or as mentioned you can use '''[store_unit]''' to copy the unit along with all its variables into a global variable which can then be accessed normally – for example with a unit stored to the variable <code>my_unit</code>, you could access the scalar unit variable <code>my_stamina</code> as <code>$my_unit.variables.my_stamina</code>.

If modifying unit variables after storing the unit, always remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.

An example of how you can filter on a unit variable in [[StandardUnitFilter]]:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Side ===

Side variables are stored on a specific side. That means that, if desired, every side could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Side variables can be created with '''[modify_side]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardSideFilter]]), or you can use '''[store_side]''' to copy the side along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_side</code>, then you could access the scalar side variable <code>wood_amount</code> as <code>$my_side.variables.wood_amount</code>.

Since there is no '''[unstore_side]''' tag, don't modify the variables in a stored side. Instead, use [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]] for the changes to be kept.

== Assigning Variables ==

Variables can be created and modified using [[ActionWML]] or [[LuaAPI/wml#wml.variables|Lua]]. There are several ways to do this:

* The '''[set_variable]''' tag can assign or modify a scalar variable using a wide variety of operations.
* The '''[set_variables]''' tag can assign or modify a container or array variable using a wide variety of operations.
* The '''[variables]''' tag can be used to set up a large number of variables all at once.
* The '''{VARIABLE}''' macro can assign a new scalar variable with a given value.
* The '''{VARIABLE_OP}''' macro can modify an existing scalar variable using a wide variety of operations.
* There are several ways to assign variables from Lua. They won't be covered here, however.

=== The [set_variable] tag ===

The '''[[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]''' tag can be directly used as ActionWML to work with global variables, or it can be placed in the '''[modify_unit]''' or '''[modify_side]''' ActionWML tags to work with unit or side variables, respectively. See the documentation of these tags for details.

=== The [set_variables] tag ===

As of 1.18.0, the '''[[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]''' tag can only be used as ActionWML. Support for placing it in '''[modify_unit]''' and '''[modify_side]''' is planned. See the documentation of these tags for details.

=== The [variables] tag ===

Unlike the others, the '''[variables]''' tag cannot be directly used as ActionWML. It can be used in a number of other places, however:

* Placed in a scenario tag to assign initial global variables at scenario start.
* Placed in a '''[side]''' tag to assign initial side variables at scenario start.
* Placed in a '''[unit]''' tag to assign initial unit variables when the unit is spawned.
* Placed in '''[leader]''' with the same meaning as in '''[unit]'''.
* Placed in '''[modify_unit]''' and '''[modify_side]''' ActionWML to adjust the values of several variables at once using "merge mode" (see '''[set_variables]''' documentation for the explanation of how this works).
* Seen in saved games to describe the current value of each variable when the game was saved.

When using the '''[variables]''' tag, a scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

== Reading Variables ==

Variables can be queried in a variety of ways, including substitutions, [[ConditionalWML]], [[Wesnoth Formula Language]], and Lua. The Lua methods won't be covered here, however.

=== Conditionals ===

Variables may be compared by using '''[variable]''' within an [if] or [while] tag. The '''{VARIABLE_CONDITIONAL}''' macro can also be used for this purpose. For more information, please refer to [[ConditionalActionsWML]].

=== Filters ===

In [[StandardUnitFilter|unit filters]], the '''[variables]''' tag can be used in '''[filter_wml]''' to check the value of unit variables, respectively.

Both unit filters and [[StandardSideFilter|side filters]] also support querying variables via WFL. The details of how this works is not covered here, however.

=== Variable Substitution ===

When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.

In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.

Variable substitutions (and also formula substitutions, see [[SyntaxWML#formula substitution|here]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.

For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substitute in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

The most common use-case for this is using a scalar variable to index an array variable, for example <code>$houses[$n].title</code>. In cases where substitution will occur more than once, such as a nested event, it can also be used to delay substitution to the second phase by simply adding a pipe directly after the dollar sign. The first round of substitution will remove the pipe and stop there (moving on to the next substitution left of it, if any), and then the second round of substitution will detect the variable and replace it.

Here's a more complete example:

<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute values are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
* The value of '''literal=''' inside [set_variable]
* The contents of '''[literal]''' inside [set_variables]
* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, when used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).

=== [insert_tag] ===

The '''[insert_tag]''' tag inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form.

This works in any tag that permits sub-tags and supports variable substitution. That means that, like variable substitution, it will ''not'' work in places that use [[#Literal Mode|literal mode]].

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': The name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

Here's an example of its use:

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== Clearing Variables ==

This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]]. It can also be done from Lua.

Like '''[set_variable]''', the '''[clear_variable]''' tag can either be used as ActionWML or placed inside '''[modify_unit]''' or '''[modify_side]'''.

== Automatically Stored Variables ==
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once one of their attributes is accessed for the first time. This means that one can sometimes get incorrect results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

== Variable Usage Examples ==
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Tutorial ==

* [[/How_to_use_variables|How to use variables]]

LuaAPI/types/widget

2026-02-16T03:47:19Z

Celtic Minstrel: /* Widget Length */ Add stacked_widget

<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]'''

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]'''

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/gui/widget

2026-02-16T03:45:46Z

Celtic Minstrel: /* clear_items */ Fix name

The '''gui.widget''' module contains functions for managing widgets in custom GUI2 dialogs. Since these functions take a [[LuaAPI/types/widget|widget userdata]] as the first parameter, they can only be used in the preshow or postshow of a GUI2 dialog (directly or indirectly). However, the table is available at all times, and additional methods can be installed here for unusual needs.

'''Note:''' The '''gui.widget.set_callback''' is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget.

=== focus ===

* '''gui.widget.focus'''(''widget'')
* ''widget'':'''focus'''()

Switches the keyboard focus to the widget. This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

=== set_canvas ===

* '''gui.widget.set_canvas'''(''widget'', ''layer index'', ''content'')
* ''widget'':'''set_canvas'''(''layer index'', ''content'')

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget. The content of the WML table depends on which shape is used:

* [[GUICanvasWML#Circle|Circle]]
* [[GUICanvasWML#Image|Image]]
* [[GUICanvasWML#Line|Line]]
* [[GUICanvasWML#Bounded_Shape|common attributes of rectangles, round rectangles and text]]
* [[GUICanvasWML#Rectangle|Rectangle]]
* [[GUICanvasWML#Rounded_Rectangle|Rounded Rectangle]]
* [[GUICanvasWML#Text|Text]]

<syntaxhighlight lang=lua>
-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
dialog:set_canvas(2, {
wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})
</syntaxhighlight>

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

=== add_item ===

* '''gui.widget.add_item'''(''widget'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item'''([''position'']) → ''the new item'', ''position''

Add an item to a container widget, for example a listbox. Returns the created item as a [[LuaAPI/types/widget|widget userdata]].

=== add_item_of_type ===

* '''gui.widget.add_item_of_type'''(''widget'', ''category'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item_of_type'''(''category'', [''position'']) → ''the new item'', ''position''

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews.

=== remove_items_at ===

* '''gui.widget.remove_items_at'''(''widget'', ''position'', ''count'')
* ''widget'':'''remove_items_at'''(''position'', ''count'')

Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed.

=== clear_items ===
{{DevFeature1.19|5}}

* '''gui.widget.clear_items'''(''widget'')
* ''widget'':'''clear_items'''()

Removes all elements of a container type widget.

=== find ===

* '''gui.widget.find'''(''root widget'', ...)
* ''widget'':'''find'''(...)

Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list':

<syntaxhighlight lang=lua>
dialog:find('unit_list', 2, 'preview_panel')
</syntaxhighlight>

This is more or less equivalent to the following:

<syntaxhighlight lang=lua>
dialog.unit_list[2].preview_panel
</syntaxhighlight>

However, if the path comes from a variable, the functional form may be more convenient:

<syntaxhighlight lang=lua>
dialog:find(table.unpack(path))
</syntaxhighlight>

=== close ===

* '''gui.widget.close'''(''dialog'')
* ''widget'':'''close'''()

Closes the dialog.

[[Category:Lua Reference]]

LuaAPI/types/widget

2026-02-16T03:43:51Z

Celtic Minstrel: /* Widget Callbacks */ Capitalization

<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]'''

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]'''

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]'''

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:43:39Z

Celtic Minstrel: /* Widget Methods */ Capitalization

<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]'''

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]'''

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]'''

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:43:23Z

Celtic Minstrel: /* Widget Length */ New section

<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]'''

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]'''

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]'''

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

AbilitiesWML

2026-02-11T05:35:28Z

Celtic Minstrel: /* Common keys and tags for every weapon special */ Link to the section

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. 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 chosen.
* '''[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]'' and ''[regenerate]'' abilities ===
* '''value''': the amount healed.
* '''poison''': When the healed unit is poisoned, then unit takes usual poison damage instead. Interaction with poison can be changed with these values:
** ''cured'' - stops poison damage and heals the poison instead of healing
** ''slowed'' - stops poison damage instead of healing

* Use common keys and tags for abilities with a value.

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

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

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

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

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

==== Common calculations ====

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

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

Prior to 1.19.4:

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

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

{{DevFeature1.17|23}}

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

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

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

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

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

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

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

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

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

[[Category:WML Reference]]

FilterWML

2026-02-05T00:32:02Z

Celtic Minstrel: /* Filtering Abilities */ New section

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Abilities ==
Occasionally, you need to filter for matching unit abilities or weapon specials. For this, an ability filter can be used.
Ability filters are represented on this site by the phrase "standard ability filter".

See [[StandardAbilityFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane' or customised type. {{DevFeature1.17|23}} [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location. Does not work in 1.16. {{DevFeature1.17|17}} Works again.
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''[filter_special]''': {{DevFeature1.19|6}} Filter on a weapon special by using[[StandardAbilityFilter]]
** '''active''': if active=yes, true if the special is active at the current location. If active=no, true whether or not it's currently active, in this case, one special encoded in [attack] can be checked.
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''attacks_used''': {{DevFeature1.17|13}} filter on attack's attack cost
* '''min_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''max_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable. Keys supported after specific version: {{DevFeature1.17|13}} '''attacks_used'''. {{DevFeature1.19|4}} '''min_range''', '''max_range'''.

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering on WML data ==

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between '''<>''' needs to be replaced by the actual data to be filtered for. The following conventions are possible:

* ''<key>'''='''<value>'': Means that the key '''key''' must be present with the specified '''value'''.
* '''glob_on_'''''<key>'''''='''''<glob>'': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In a glob, the '''*''' character matches any sequence of characters, while the '''?''' character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_'''''<key>'''''=*''' in a '''[not]''' tag.
* '''['''''<some_tag>''''']''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.

== Tutorial ==
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[AnimationWML#Animation_Filtering|Animation filtering]]
* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]
* [[FilterWML/Examples - How to use Filter]]

[[Category: WML Reference]]

Modifying AI Components

2026-02-01T07:36:45Z

Celtic Minstrel: /* [modify_ai] Tag Syntax */ Be clearer about the basic format of the new configuration tag.

== Methods for Modifying the AI Mid Scenario ==

The AI and its parameters are usually set up at the beginning of a scenario and often left unchanged for the entire scenario. See [[AiWML]] and [[Creating Custom AIs]] for instructions on how to do this, or the complete list of AI resources at [[Wesnoth AI]].

Sometimes it is, however, desirable to modify parts or all of the AI mid-scenario. Wesnoth provides different tools to accomplish this:
* Standard aspects can be modified mid scenario using the [modify_side] tag
* Composite aspects, goals and all other AI components can be modified mid scenario using the [modify_ai] tag.
** A large number of helper macros are available to facilitate these tasks.
* Micro AIs can be modified mid scenario using the [micro_ai] tag
** The [micro_ai] tag is always used in an event. There is no difference between using it at the beginning of the scenario, that is, in a ''prestart'' or ''start'' event, or in any other event. We therefore refer to the [[Micro AIs]] page for this.

== Using [modify_side] to Change Aspects Mid Scenario ==

The [modify_side] tag can contain an [ai] tag for modifying aspects while a game is in progress. This works, however, <u>only</u> for [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]. An example is
<syntaxhighlight lang='wml'>
[modify_side]
side=2
[ai]
aggression=0.765
[/ai]
[/modify_side]
</syntaxhighlight>

[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|Composite aspects]] and all other [[Wesnoth_AI_Framework#Types_of_AI_Components|AI components]] cannot be modified in this way. Use the [modify_ai] tag described below for these tasks.

Note that modifying an aspect in this fashion does not replace the [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]] used to define the aspect in the AI configuration. It simply adds another facet that then takes precedence over the already existing ones. In most situations, this does not make a difference, but there might be some cases (for example when facets are only defined for certain times of day or turns), when it might be necessary to replace the existing facet rather than adding a new one. This can also be done using the [modify_ai] tag as described below.

Note that it is, in principle, also possible to define the aspect using this syntax
<syntaxhighlight lang='wml'>
[modify_side]
side=2
[ai]
[aspect]
id=aggression
[facet]
value=0.765
[/facet]
[/aspect]
[/ai]
[/modify_side]
</syntaxhighlight>
However, as this <u>only</u> works for standard aspects which can also be set with the simpler syntax shown above, there is really no point in doing so.

== The [modify_ai] Tag ==

The [modify_ai] tag is a tool for modifying [[Wesnoth_AI_Framework#Stages|stages]], [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|candidate actions]], [[Wesnoth_AI_Framework#Aspects_and_Goals|aspects and goals]] of the active AI on the fly at any time during a scenario. Since all this functionality is packed into a single tag, its syntax is a bit more complex than that of other tags. To facilitate this, Wesnoth also provides a large variety of [[#Modifying_AI_Components_Helper_Macros|helper macros]], but even for using those one still needs to understand the general syntax of the [modify_ai] tag.

Note that the [modify_ai] tag can be used both in [event] tags and in [side][ai], [era][ai] or [modification][ai] tags, meaning it can also be used to change the AI configuration at game setup time.

=== [modify_ai] Tag Syntax ===

The [modify_ai] tag takes the following keys:

* '''side''': The side of the AI to be modified if used in an event. This key is not needed if used in [side][ai]. In fact, if given there, it is simply ignored.
** More generally, a [[StandardSideFilter]] can be used.
* '''action''': (string) The action to take concerning the component. The following values are allowed:
** 'add': Add a component.
** 'change': Change an existing component.
** 'delete': Delete an existing component.
** 'try_delete': Delete a component if it exists. This does not produce a warning if [modify_ai] fails to change the AI.
* '''path''': (string) Defines the component of the AI to be modified. See below.
* '''New configuration''' for the component (only when adding or changing): This depends on the type of component and is shown in the examples below. It must always be a tag whose name matches the final component of the '''path'''.

====Possible values for [modify_ai]path ====

Depending on the AI component one wants to modify, the '''path''' key can take on different values. The general form of a path is a series of elements separated by dots; each element consists of a component type followed by an ID in square brackets. In many cases, the path consists of only a single level (goals or stages) or two levels (aspect/facet and stage/CA), but {{DevFeature1.13|5}} three or even four levels is occasionally possible with aspects.

The possible toplevel elements in a path are:

* '''aspect'''[''aspect_id'']: Select the aspect with the specified name. The ''aspect_id'' is the name of a known aspect, for example '''aggression'''.
* '''goal'''[''goal_id'']: Select the goal with the specified name.
* '''stage'''[''stage_id'']: Select the state with the specified name. Usually, the ''stage_id'' will be '''main_loop''', though in unusual setups there could be other stages with different IDs.

Other possible elements in a path are:

* '''facet'''[''facet_id'']: May only appear under an '''aspect''', or nested in another '''facet'''. Selects a specific facet in a composite aspect.
* '''recruit'''[''recruit_id'']: May only appear under '''aspect[recruitment_instructions]''', usually nested within a '''facet'''. Selects a single recruitment instruction defined by a '''recruit''', '''pattern''', or '''total''' tag.
* '''limit'''[''recruit_id'']: May only appear under '''aspect[recruitment_instructions]''', usually nested within a '''facet'''. Selects a single recruitment limit defined by a '''limit''' tag.
* '''candidate_action'''[''ca_id'']: May only appear under a '''stage'''. See [[RCA_AI#Available_Candidate_Actions|here]] for the ids of the default CAs.

The ''goal_id'', ''stage_id'', ''facet_id'', and ''recruit_id'' can take on any of the following values:
* A string: Identify the component by the id used when defining it (the '''id''' key)
* An integer, starting at 0: Select a component by its index, in the order in which they were defined
* '''*''': Select all components of this type
* Blank: Used when adding new components, where the ID will be specified in the tag and should not be duplicated in the path.

Some examples:

* Select facet 'quark' of the aggression (composite) aspect: <code>aspect[aggression].facet[quark]</code>
* {{DevFeature1.13|5}} Select recruit job 'bobby' of the recruitment_instructions aspect defined as a standard aspect: <code>aspect[recruitment_instructions].recruit[bobby]</code>
* {{DevFeature1.13|5}} Select recruit limit 'limit_wc' of the recruitment_instructions aspect defined as a standard aspect: <code>aspect[recruitment_instructions].limit[limit_wc]</code>
* {{DevFeature1.13|5}} Select the default facet of the (composite) village_value aspect: <code>aspect[village_value].facet[default_facet]</code>
* Select goal 'lighthouse': <code>goal[lighthouse]</code>
* Select the 'main_loop' stage: <code>stage[main_loop]</code>
* Select candidate action 'healer_support' of the 'main_loop' stage: <code>stage[main_loop].candidate_action[healer_support]</code>
* Select an unspecified facet in the composite 'aggression' aspect: <code>aspect[aggression].facet[]</code>

If all this seemed a bit theoretical, don't worry. Below, we provide many examples for how to do this in practice.

== Modifying AI Components Helper Macros ==

A large number of helper macros are available to simplify the WML needed for modifying AI components. These macros are defined in file 'data/core/macros/ai.cfg', see the [http://www.wesnoth.org/macro-reference.xhtml#file:ai.cfg list] of available macros or the [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/ai.cfg full definitions].

'''Notes on the macros:'''

* We do not describe the individual macros here. There are way too many of them and, quite frankly, most of them are not really needed as they barely simplify the syntax compared to the full [modify_ai] tag. Instead, a variety of examples are given in the following sections. If in doubt how to use a macro, or if you want to see all available macros, check out their definitions at the link above.
* There are several macros with ''SIMPLE_ASPECT'' in the name. Formally, there is no such things as a ''simple'' aspect, only ''standard'' and ''composite'' aspects. This is just a convention used by the macros for standard aspects which consist of a single scalar value. Thus, all simple aspects (such as ''aggression'') are standard aspects, but not all standard aspects (such as ''avoid'') are simple aspects.
* There are several macros with ''ALWAYS_ASPECT'' in the name. These are macros for aspects which apply at all times of day and at all turns. However, the 'always' used as macro argument is actually the facet id, not the values of either the ''time_of_day'' or ''turns'' keys. This is done so that the facet ids are standardized should removal of these aspects be desired later.

== Modifying AI Component Examples ==

=== Modifying Standard Aspects ===

As was shown above, standard aspects, and <u>only</u> standard aspects, can be modified using [modify_side]. A simple example is
<syntaxhighlight lang='wml'>
[modify_side]
side=1
[ai]
aggression=0.765
[/ai]
[/modify_side]
</syntaxhighlight>
This is the simplest syntax for modifying standard aspects (without using macros). However, as we explain [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]], internally <u>all</u> aspects are set up as composite aspects. Thus, [modify_ai] and composite aspect syntax can also be used for simple aspects and we use this example to demonstrate this:
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=aspect[aggression].facet[]
[facet]
value=0.765
[/facet]
[/modify_ai]
</syntaxhighlight>
Finally, using one of the helper macros results in this:
<syntaxhighlight lang='wml'>
{MODIFY_AI_ADD_SIMPLE_ASPECT 1 aggression 0.765}
</syntaxhighlight>

Removing this setting of the aggression aspect again is done as:
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[0]
[/modify_ai]
</syntaxhighlight>
Assuming we know that it is the first non-default facet of the ''aggression'' aspect that needs to be removed. If, instead, we want to remove all custom definitions of aggression, we use
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[*]
[/modify_ai]
</syntaxhighlight>

Using macros, this is done with
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_ASPECT 1 aggression 0}
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_ASPECT 1 aggression "*"}
</syntaxhighlight>

If we don't know the number of the facet and do not want to remove all of them, we need to assign an id to the facet defining the aspect (the simple syntax of the very first example cannot be used in that case) and use that id for selective removal. For example, the definition could look like this
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=aspect[aggression].facet[]
[facet]
id=my_custom_aggression
value=0.765
[/facet]
[/modify_ai]
</syntaxhighlight>
and removal like this
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[my_custom_aggression]
[/modify_ai]
</syntaxhighlight>

The macro versions of these are
<syntaxhighlight lang='wml'>
{MODIFY_AI_ADD_ASPECT 1 aggression (
[facet]
id=my_custom_aggression
value=0.765
[/facet]
)}
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_ASPECT 1 aggression my_custom_aggression}
</syntaxhighlight>

Finally, we stress that a ''standard'' aspect does not need to be restricted to a single, scalar value. For example, ''avoid'' is a standard aspect and can be defined using both types of syntax, such as
<syntaxhighlight lang='wml'>
[modify_side]
side=1
[ai]
[avoid]
x,y=20,16
radius=6
[/avoid]
[/ai]
[/modify_side]
</syntaxhighlight>
or
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=aspect[avoid].facet[]
[facet]
[value]
x,y=20,16
radius=6
[/value]
[/facet]
[/modify_ai]
</syntaxhighlight>
Finale note: Any aspect listed at [[AiWML]] which is not specifically pointed out to be a composite aspect (and there are very few of those), is a standard aspect.

=== Modifying Composite Aspects ===

A small number of the aspects listed at [[AiWML]] are available in ''composite'' aspect syntax only. However, there is really nothing new about modifying them compared to what is shown above for ''standard'' aspects. The only difference (as far as modifying the aspects is concerned) is that we <u>have to</u> use composite aspect syntax, standard aspect syntax does not work. Thus, we only show one example of the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|''attacks'' aspect]] here.
<syntaxhighlight lang='wml'>
[modify_ai]
side=2
action=add
path=aspect[attacks].facet[]
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/modify_ai]
</syntaxhighlight>

=== A Few More Notes on Modifying Aspects ===

* The aspect itself and its [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|[default]]] facet cannot be deleted, only the custom facets. {{DevFeature1.13|5}} However, they can be changed, replacing them with a new definition. (The id attribute must match when changing an aspect.) This could change a standard aspect to a composite aspect or vice versa.
* For standard aspects, it is generally not necessary to delete custom facets. One can simply overwrite the current value with a new one. The only times when one might have to remove a standard aspect is when it is defined for specific times of day or turns, or when it is defined so many times that it might bloat the AI configuration (and therefore the savefile).
* We can also use <code>action=change</code> to delete an existing facet and overwrite it with a new definition. If <code>*</code> is used as ''facet_id'', this deletes all existing facets of this aspect and replaces them with a single facet with the new definition.
* Adding a facet with the same ''id'' as an existing facet overwrites the previous occurrence, making this equivalent to changing that facet.
* If in doubt about the exact syntax of a given aspect, one can always open the gamestate inspector (by typing <code>:inspect</code> in-game in debug mode) and check out the [default] tag of the respective aspect under 'ai config full' for a given side (team). Note though that it might be necessary to play through at least one partial turn of that side, as the AI config of the side is not necessarily fully initialized until that happens.

=== Modifying Goals ===

Goals can be added and removed using a syntax that is very similar to that for composite aspects
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=goal[]
[goal]
id=my_custom_goal
[criteria]
side=3
[/criteria]
value=5
[/goal]
[/modify_ai]
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete
path=goal[my_custom_goal]
[/modify_ai]
</syntaxhighlight>
Note that we assigned a custom id to the goal here, that was then used for removal. We could also use the method described above for aspects, using the number of the goal or <code>*</code>.

The macro versions of these examples are
<syntaxhighlight lang='wml'>
{MODIFY_AI_ADD_GOAL 1 (
[goal]
id=my_custom_goal
[criteria]
side=3
[/criteria]
value=5
[/goal]
)}
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_GOAL 1 my_custom_goal}
</syntaxhighlight>

=== Modifying Candidate Action of the ''main_loop'' Stage ===

The syntax for modifying candidate actions is entirely equivalent to that for aspects and goals shown above. If one wants to, for example, set up an AI that does not fight, this can be done by removing the ''combat'' CA. {{DevFeature1.15|3}} There are now additional CAs which also perform attacks. Check out [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|the candidate actions of the default AI]] to see which CAs need to be remove in order to produce an AI that truly does not attack.
<syntaxhighlight lang='wml'>
[modify_ai]
side=2
action=delete
path=stage[main_loop].candidate_action[combat]
[/modify_ai]
</syntaxhighlight>
or
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop combat}
</syntaxhighlight>

Adding a [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions|custom Lua candidate action]] is done as follows
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=stage[main_loop].candidate_action[]
[candidate_action]
engine=lua
name=return_guardian_bob
id=return_guardian_bob
max_score=100010
location="~add-ons/my_addon/lua/return_guardian.lua"
eval_parms="id = 'Bob', return_x = 10, return_y = 15"
exec_parms="id = 'Bob', return_x = 10, return_y = 15"
[/candidate_action]
[/modify_ai]
</syntaxhighlight>

We'll omit the macro version here as it is almost identical to previous examples.

=== Modifying Stages ===

Working with a single stage, the [[Wesnoth_AI_Framework#Stages|''main_loop'' stage]], should be sufficient for essentially all Wesnoth AI projects these days. It should therefore rarely ever be necessary to add or remove stages any more. It can, however, be done in the same way as for the other AI components. The macro definitions linked to above can be used as syntax reference if you ever need to do so.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Modifying AI Components

2026-02-01T07:31:47Z

Celtic Minstrel: /* Possible values for [modify_ai]path */ Try to be more clear about what's possible

== Methods for Modifying the AI Mid Scenario ==

The AI and its parameters are usually set up at the beginning of a scenario and often left unchanged for the entire scenario. See [[AiWML]] and [[Creating Custom AIs]] for instructions on how to do this, or the complete list of AI resources at [[Wesnoth AI]].

Sometimes it is, however, desirable to modify parts or all of the AI mid-scenario. Wesnoth provides different tools to accomplish this:
* Standard aspects can be modified mid scenario using the [modify_side] tag
* Composite aspects, goals and all other AI components can be modified mid scenario using the [modify_ai] tag.
** A large number of helper macros are available to facilitate these tasks.
* Micro AIs can be modified mid scenario using the [micro_ai] tag
** The [micro_ai] tag is always used in an event. There is no difference between using it at the beginning of the scenario, that is, in a ''prestart'' or ''start'' event, or in any other event. We therefore refer to the [[Micro AIs]] page for this.

== Using [modify_side] to Change Aspects Mid Scenario ==

The [modify_side] tag can contain an [ai] tag for modifying aspects while a game is in progress. This works, however, <u>only</u> for [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]. An example is
<syntaxhighlight lang='wml'>
[modify_side]
side=2
[ai]
aggression=0.765
[/ai]
[/modify_side]
</syntaxhighlight>

[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|Composite aspects]] and all other [[Wesnoth_AI_Framework#Types_of_AI_Components|AI components]] cannot be modified in this way. Use the [modify_ai] tag described below for these tasks.

Note that modifying an aspect in this fashion does not replace the [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]] used to define the aspect in the AI configuration. It simply adds another facet that then takes precedence over the already existing ones. In most situations, this does not make a difference, but there might be some cases (for example when facets are only defined for certain times of day or turns), when it might be necessary to replace the existing facet rather than adding a new one. This can also be done using the [modify_ai] tag as described below.

Note that it is, in principle, also possible to define the aspect using this syntax
<syntaxhighlight lang='wml'>
[modify_side]
side=2
[ai]
[aspect]
id=aggression
[facet]
value=0.765
[/facet]
[/aspect]
[/ai]
[/modify_side]
</syntaxhighlight>
However, as this <u>only</u> works for standard aspects which can also be set with the simpler syntax shown above, there is really no point in doing so.

== The [modify_ai] Tag ==

The [modify_ai] tag is a tool for modifying [[Wesnoth_AI_Framework#Stages|stages]], [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|candidate actions]], [[Wesnoth_AI_Framework#Aspects_and_Goals|aspects and goals]] of the active AI on the fly at any time during a scenario. Since all this functionality is packed into a single tag, its syntax is a bit more complex than that of other tags. To facilitate this, Wesnoth also provides a large variety of [[#Modifying_AI_Components_Helper_Macros|helper macros]], but even for using those one still needs to understand the general syntax of the [modify_ai] tag.

Note that the [modify_ai] tag can be used both in [event] tags and in [side][ai], [era][ai] or [modification][ai] tags, meaning it can also be used to change the AI configuration at game setup time.

=== [modify_ai] Tag Syntax ===

The [modify_ai] tag takes the following keys:

* '''side''': The side of the AI to be modified if used in an event. This key is not needed if used in [side][ai]. In fact, if given there, it is simply ignored.
** More generally, a [[StandardSideFilter]] can be used.
* '''action''': (string) The action to take concerning the component. The following values are allowed:
** 'add': Add a component.
** 'change': Change an existing component.
** 'delete': Delete an existing component.
** 'try_delete': Delete a component if it exists. This does not produce a warning if [modify_ai] fails to change the AI.
* '''path''': (string) Defines the component of the AI to be modified. See below.
* '''New configuration''' for the component: This depends on the type of component and is shown in the examples below.

====Possible values for [modify_ai]path ====

Depending on the AI component one wants to modify, the '''path''' key can take on different values. The general form of a path is a series of elements separated by dots; each element consists of a component type followed by an ID in square brackets. In many cases, the path consists of only a single level (goals or stages) or two levels (aspect/facet and stage/CA), but {{DevFeature1.13|5}} three or even four levels is occasionally possible with aspects.

The possible toplevel elements in a path are:

* '''aspect'''[''aspect_id'']: Select the aspect with the specified name. The ''aspect_id'' is the name of a known aspect, for example '''aggression'''.
* '''goal'''[''goal_id'']: Select the goal with the specified name.
* '''stage'''[''stage_id'']: Select the state with the specified name. Usually, the ''stage_id'' will be '''main_loop''', though in unusual setups there could be other stages with different IDs.

Other possible elements in a path are:

* '''facet'''[''facet_id'']: May only appear under an '''aspect''', or nested in another '''facet'''. Selects a specific facet in a composite aspect.
* '''recruit'''[''recruit_id'']: May only appear under '''aspect[recruitment_instructions]''', usually nested within a '''facet'''. Selects a single recruitment instruction defined by a '''recruit''', '''pattern''', or '''total''' tag.
* '''limit'''[''recruit_id'']: May only appear under '''aspect[recruitment_instructions]''', usually nested within a '''facet'''. Selects a single recruitment limit defined by a '''limit''' tag.
* '''candidate_action'''[''ca_id'']: May only appear under a '''stage'''. See [[RCA_AI#Available_Candidate_Actions|here]] for the ids of the default CAs.

The ''goal_id'', ''stage_id'', ''facet_id'', and ''recruit_id'' can take on any of the following values:
* A string: Identify the component by the id used when defining it (the '''id''' key)
* An integer, starting at 0: Select a component by its index, in the order in which they were defined
* '''*''': Select all components of this type
* Blank: Used when adding new components, where the ID will be specified in the tag and should not be duplicated in the path.

Some examples:

* Select facet 'quark' of the aggression (composite) aspect: <code>aspect[aggression].facet[quark]</code>
* {{DevFeature1.13|5}} Select recruit job 'bobby' of the recruitment_instructions aspect defined as a standard aspect: <code>aspect[recruitment_instructions].recruit[bobby]</code>
* {{DevFeature1.13|5}} Select recruit limit 'limit_wc' of the recruitment_instructions aspect defined as a standard aspect: <code>aspect[recruitment_instructions].limit[limit_wc]</code>
* {{DevFeature1.13|5}} Select the default facet of the (composite) village_value aspect: <code>aspect[village_value].facet[default_facet]</code>
* Select goal 'lighthouse': <code>goal[lighthouse]</code>
* Select the 'main_loop' stage: <code>stage[main_loop]</code>
* Select candidate action 'healer_support' of the 'main_loop' stage: <code>stage[main_loop].candidate_action[healer_support]</code>
* Select an unspecified facet in the composite 'aggression' aspect: <code>aspect[aggression].facet[]</code>

If all this seemed a bit theoretical, don't worry. Below, we provide many examples for how to do this in practice.

== Modifying AI Components Helper Macros ==

A large number of helper macros are available to simplify the WML needed for modifying AI components. These macros are defined in file 'data/core/macros/ai.cfg', see the [http://www.wesnoth.org/macro-reference.xhtml#file:ai.cfg list] of available macros or the [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/ai.cfg full definitions].

'''Notes on the macros:'''

* We do not describe the individual macros here. There are way too many of them and, quite frankly, most of them are not really needed as they barely simplify the syntax compared to the full [modify_ai] tag. Instead, a variety of examples are given in the following sections. If in doubt how to use a macro, or if you want to see all available macros, check out their definitions at the link above.
* There are several macros with ''SIMPLE_ASPECT'' in the name. Formally, there is no such things as a ''simple'' aspect, only ''standard'' and ''composite'' aspects. This is just a convention used by the macros for standard aspects which consist of a single scalar value. Thus, all simple aspects (such as ''aggression'') are standard aspects, but not all standard aspects (such as ''avoid'') are simple aspects.
* There are several macros with ''ALWAYS_ASPECT'' in the name. These are macros for aspects which apply at all times of day and at all turns. However, the 'always' used as macro argument is actually the facet id, not the values of either the ''time_of_day'' or ''turns'' keys. This is done so that the facet ids are standardized should removal of these aspects be desired later.

== Modifying AI Component Examples ==

=== Modifying Standard Aspects ===

As was shown above, standard aspects, and <u>only</u> standard aspects, can be modified using [modify_side]. A simple example is
<syntaxhighlight lang='wml'>
[modify_side]
side=1
[ai]
aggression=0.765
[/ai]
[/modify_side]
</syntaxhighlight>
This is the simplest syntax for modifying standard aspects (without using macros). However, as we explain [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]], internally <u>all</u> aspects are set up as composite aspects. Thus, [modify_ai] and composite aspect syntax can also be used for simple aspects and we use this example to demonstrate this:
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=aspect[aggression].facet[]
[facet]
value=0.765
[/facet]
[/modify_ai]
</syntaxhighlight>
Finally, using one of the helper macros results in this:
<syntaxhighlight lang='wml'>
{MODIFY_AI_ADD_SIMPLE_ASPECT 1 aggression 0.765}
</syntaxhighlight>

Removing this setting of the aggression aspect again is done as:
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[0]
[/modify_ai]
</syntaxhighlight>
Assuming we know that it is the first non-default facet of the ''aggression'' aspect that needs to be removed. If, instead, we want to remove all custom definitions of aggression, we use
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[*]
[/modify_ai]
</syntaxhighlight>

Using macros, this is done with
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_ASPECT 1 aggression 0}
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_ASPECT 1 aggression "*"}
</syntaxhighlight>

If we don't know the number of the facet and do not want to remove all of them, we need to assign an id to the facet defining the aspect (the simple syntax of the very first example cannot be used in that case) and use that id for selective removal. For example, the definition could look like this
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=aspect[aggression].facet[]
[facet]
id=my_custom_aggression
value=0.765
[/facet]
[/modify_ai]
</syntaxhighlight>
and removal like this
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[my_custom_aggression]
[/modify_ai]
</syntaxhighlight>

The macro versions of these are
<syntaxhighlight lang='wml'>
{MODIFY_AI_ADD_ASPECT 1 aggression (
[facet]
id=my_custom_aggression
value=0.765
[/facet]
)}
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_ASPECT 1 aggression my_custom_aggression}
</syntaxhighlight>

Finally, we stress that a ''standard'' aspect does not need to be restricted to a single, scalar value. For example, ''avoid'' is a standard aspect and can be defined using both types of syntax, such as
<syntaxhighlight lang='wml'>
[modify_side]
side=1
[ai]
[avoid]
x,y=20,16
radius=6
[/avoid]
[/ai]
[/modify_side]
</syntaxhighlight>
or
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=aspect[avoid].facet[]
[facet]
[value]
x,y=20,16
radius=6
[/value]
[/facet]
[/modify_ai]
</syntaxhighlight>
Finale note: Any aspect listed at [[AiWML]] which is not specifically pointed out to be a composite aspect (and there are very few of those), is a standard aspect.

=== Modifying Composite Aspects ===

A small number of the aspects listed at [[AiWML]] are available in ''composite'' aspect syntax only. However, there is really nothing new about modifying them compared to what is shown above for ''standard'' aspects. The only difference (as far as modifying the aspects is concerned) is that we <u>have to</u> use composite aspect syntax, standard aspect syntax does not work. Thus, we only show one example of the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|''attacks'' aspect]] here.
<syntaxhighlight lang='wml'>
[modify_ai]
side=2
action=add
path=aspect[attacks].facet[]
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/modify_ai]
</syntaxhighlight>

=== A Few More Notes on Modifying Aspects ===

* The aspect itself and its [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|[default]]] facet cannot be deleted, only the custom facets. {{DevFeature1.13|5}} However, they can be changed, replacing them with a new definition. (The id attribute must match when changing an aspect.) This could change a standard aspect to a composite aspect or vice versa.
* For standard aspects, it is generally not necessary to delete custom facets. One can simply overwrite the current value with a new one. The only times when one might have to remove a standard aspect is when it is defined for specific times of day or turns, or when it is defined so many times that it might bloat the AI configuration (and therefore the savefile).
* We can also use <code>action=change</code> to delete an existing facet and overwrite it with a new definition. If <code>*</code> is used as ''facet_id'', this deletes all existing facets of this aspect and replaces them with a single facet with the new definition.
* Adding a facet with the same ''id'' as an existing facet overwrites the previous occurrence, making this equivalent to changing that facet.
* If in doubt about the exact syntax of a given aspect, one can always open the gamestate inspector (by typing <code>:inspect</code> in-game in debug mode) and check out the [default] tag of the respective aspect under 'ai config full' for a given side (team). Note though that it might be necessary to play through at least one partial turn of that side, as the AI config of the side is not necessarily fully initialized until that happens.

=== Modifying Goals ===

Goals can be added and removed using a syntax that is very similar to that for composite aspects
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=goal[]
[goal]
id=my_custom_goal
[criteria]
side=3
[/criteria]
value=5
[/goal]
[/modify_ai]
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=delete
path=goal[my_custom_goal]
[/modify_ai]
</syntaxhighlight>
Note that we assigned a custom id to the goal here, that was then used for removal. We could also use the method described above for aspects, using the number of the goal or <code>*</code>.

The macro versions of these examples are
<syntaxhighlight lang='wml'>
{MODIFY_AI_ADD_GOAL 1 (
[goal]
id=my_custom_goal
[criteria]
side=3
[/criteria]
value=5
[/goal]
)}
</syntaxhighlight>
and
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_GOAL 1 my_custom_goal}
</syntaxhighlight>

=== Modifying Candidate Action of the ''main_loop'' Stage ===

The syntax for modifying candidate actions is entirely equivalent to that for aspects and goals shown above. If one wants to, for example, set up an AI that does not fight, this can be done by removing the ''combat'' CA. {{DevFeature1.15|3}} There are now additional CAs which also perform attacks. Check out [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|the candidate actions of the default AI]] to see which CAs need to be remove in order to produce an AI that truly does not attack.
<syntaxhighlight lang='wml'>
[modify_ai]
side=2
action=delete
path=stage[main_loop].candidate_action[combat]
[/modify_ai]
</syntaxhighlight>
or
<syntaxhighlight lang='wml'>
{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop combat}
</syntaxhighlight>

Adding a [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions|custom Lua candidate action]] is done as follows
<syntaxhighlight lang='wml'>
[modify_ai]
side=1
action=add
path=stage[main_loop].candidate_action[]
[candidate_action]
engine=lua
name=return_guardian_bob
id=return_guardian_bob
max_score=100010
location="~add-ons/my_addon/lua/return_guardian.lua"
eval_parms="id = 'Bob', return_x = 10, return_y = 15"
exec_parms="id = 'Bob', return_x = 10, return_y = 15"
[/candidate_action]
[/modify_ai]
</syntaxhighlight>

We'll omit the macro version here as it is almost identical to previous examples.

=== Modifying Stages ===

Working with a single stage, the [[Wesnoth_AI_Framework#Stages|''main_loop'' stage]], should be sufficient for essentially all Wesnoth AI projects these days. It should therefore rarely ever be necessary to add or remove stages any more. It can, however, be done in the same way as for the other AI components. The macro definitions linked to above can be used as syntax reference if you ever need to do so.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Roadmap

2026-01-25T18:10:10Z

Celtic Minstrel: Redirected page to 1.19 Roadmap

#REDIRECT [[1.19 Roadmap]]

Wesnoth Formula Language

2026-01-25T06:59:30Z

Celtic Minstrel: /* Action Functions */ Add missing header

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

The Wesnoth Formula Language is a functional language used to evaluate expressions within the game engine. It allows performing calculations that would not otherwise be possible using only WML. For example, to have an event trigger when a unit has less than half its hitpoints, you could write the following as the event's filter:

<syntaxhighlight lang=wml>
[filter]
formula = "(hitpoints < max_hitpoints / 2)"
[/filter]
</syntaxhighlight>

The '''formula''' key is a part of [[StandardUnitFilter]] that accepts a condition written as WFL. The part inside the quotes is the WFL formula. This example will evaluate to true if the unit's '''hitpoints''' are less than half its '''max_hitpoints'''.

== Data Types and Operators ==

Wesnoth Formula Language has seven basic data types – [[#Numbers|integers]], [[#Numbers|real numbers]] (usually called "decimals"), [[#Strings|strings]], [[#Lists|lists]], [[#Maps|maps]], [[#Objects|objects]], and [[#Other Types and Operators|null]].

=== Numbers ===

The most common use of WFL is for simple calculations involving numbers. For this, the standard arithmetic operators (<code>+ - * / %</code>) work as you would expect, performing addition, subtraction, multiplication, division, and remainder. {{DevFeature1.13|5}} The remainder operator even works on decimal numbers, producing the integer remainder of the division.

The only caveat to watch out for is that <code>/</code> rounds down when used on integers. For example, <syntaxhighlight lang='wfl' inline>5 / 2</syntaxhighlight> will evaluate to <code>2</code>. To avoid this, make sure at least one of the numbers includes a decimal point (or use [[#as_decimal|as_decimal]] if variables are involved) - <syntaxhighlight lang='wfl' inline>5.0 / 2</syntaxhighlight> will evaluate to <code>2.5</code>.

Note that WFL supports only three decimal places of precision for decimal numbers; beyond that it will still be rounded down. (So <syntaxhighlight lang='wfl' inline>1.0 / 16</syntaxhighlight> will evaluate to <code>0.062</code> instead of <code>0.0625</code>.) The <code>^</code> operator performs exponentiation (raising to a power) - for example, <syntaxhighlight lang='wfl' inline>2 ^ 3</syntaxhighlight> evaluates to <code>8</code>

You can also use the standard comparison operators (<code>= != < <= > >=</code>) on numbers. This is often useful in unit filters - for example, a formula of <syntaxhighlight lang='wfl' inline>hitpoints < max_hitpoints / 2</syntaxhighlight> will match only if the unit is at less than half health. Comparison operators return 1 for true and 0 for false; there is no boolean type. Comparing values of different types will always return 0, with one exception – comparing an integer and decimal number will work as expected.

One final numeric operator exists - the dice roll. The syntax <syntaxhighlight lang='wfl' inline>3d12</syntaxhighlight> will roll three 12-sided dice and return the sum of the results. Note however that this is not multiplayer-safe, so using it can and will produce OOS errors. {{DevFeature1.13|5}} The dice operator is now synced and should be safe for use in multiplayer contexts.

'''Note:''' {{DevFeature1.13|5}} Some numeric operations will return null instead of a number. This usually involves the exponentiation operator - for example, <syntaxhighlight lang='wfl' inline>(-2) ^ 0.5</syntaxhighlight> attempts to take the square root of -2, which doesn't exist, so it returns null to indicate this. Dividing by zero also returns null, as well as certain [[#Numeric Functions|math functions]] in appropriate circumstances.

=== Strings ===

WFL also supports strings, which must be enclosed in single quotes (<syntaxhighlight lang='wfl' inline>'like this'</syntaxhighlight>). The comparison operators (<code>= != < <= > >=</code>) also work on strings, performing lexicographical comparison (ie, alphabetical order). The comparison is case sensitive.

{{DevFeature1.13|5}}

Strings can be concatenated with the concatenation operator <code>..</code>. They also support interpolations enclosed in square brackets, the contents of which can be any valid formula. For example:

<syntaxhighlight lang='wfl'>
'Some text: [a + b]' where a = 12, b = 10
</syntaxhighlight>

results in the string <code>Some text: 22</code>. (The <code>where</code> operator is explained [[#Variables|below]].)

If you need to include a literal square bracket in a string, write <code>[(]</code> or <code>[)]</code>. For a literal single quote, you can write <code>[']</code>. For example:

<syntaxhighlight lang='wfl'>
'[(]It[']s bracketed![)]'
</syntaxhighlight>

results in the string <code>[It's bracketed!]</code>.

You can index the characters or words of a string with the following syntax:

<syntaxhighlight lang='wfl'>
'Hello World'.char[4]
'Hello World'.word[1]
</syntaxhighlight>

These return <code>o</code> and <code>World</code>, respectively. A third option is also available, <code>item</code>, which splits the string on commas but allows parentheses to prevent a portion of the string from being split up. For example:

<syntaxhighlight lang='wfl'>
'First Item,Second Item,Third Item'.item[1]
'a,b,(c,d,e),f,g'.item[2]
</syntaxhighlight>

These return <code>Second Item</code> and <code>(c,d,e)</code>, respectively. When not providing index, list is returned.

<syntaxhighlight lang='wfl'>
'Hello World'.char = ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd']
'Hello World'.word = ['Hello', 'World']
'a,b,(c,d,e),f,g'.item = ['a', 'b', '(c,d,e)', 'f', 'g']
</syntaxhighlight>

=== Lists ===

A list is a sequence of values represented as square brackets, [], surrounding a comma-separated list. For instance:

<syntaxhighlight lang='wfl'>
[ 1, 5, 'abc' ]
</syntaxhighlight>

The comparison operators work on lists, performing lexicographical comparison. A specific list index can be obtained with the indexing operator, like this: <syntaxhighlight lang='wfl' inline>my_list[index]</syntaxhighlight>. The first element of a list is numbered 0.

There are four ''vector operators'' (<code>.+ .- .* ./</code>) that perform entrywise operations on lists. For example, <syntaxhighlight lang='wfl' inline>[1,2,3] .+ [12,2,8]</syntaxhighlight> produces <code>[13,4,11]</code>. Both lists must be of the same length to use these operators, and of course, they must contain only numbers.

{{DevFeature1.13|5}}

A negative list index now counts from the end of the list - <code>-1</code> refers to the last element. You can check if an element exists in a list using the <code>in</code> operator. Lists can also be joined with the concatenation operator <code>..</code>, and sliced using the range operator <code>~</code>. In fact, the range operator produces a list of consecutive numbers, and in fact any list of numbers can be used to index a list - the result is to take the elements at the requested indices, in order. Some examples:

<syntaxhighlight lang='wfl'>
[1, 7, 'abc', 2.5, 'foobar', 127][1~3]
(10~20)[[0,-1]]
[1, 7, 'abc', 2.5, 'foobar', 127][[2,4]]
</syntaxhighlight>

These result in the following lists:

[7, 'abc', 2.5]
[10,20]
['abc', 'foobar']

=== Maps ===

A map is a sequence of key-value pairs. For example:

<syntaxhighlight lang='wfl'>
[12 -> 'Hello', [1,2] -> 9, 'abc' -> 1.5]
</syntaxhighlight>

The comparison operators work on maps. A specific element of a map can be obtained with the indexing operation. In the above example, the following conditions are all true (assuming the map is in a variable called <code>self</code>):

* <syntaxhighlight lang='wfl' inline>self[12] = 'Hello'</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self[[1,2]] = 9</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self['abc'] = 1.5</syntaxhighlight>

{{DevFeature1.13|5}}

You can now use the <code>in</code> operator to test if a key exists in the map. You can also access string keys using the dot operator <code>.</code> as long as they are valid identifiers. (Valid identifiers contain letters and underscores only; no digits are permitted.)

Note that the selection indexing that lists use is ''not'' valid for maps - a list can be used as a key, after all.

Though it's rarely needed, it's possible to define an empty map with <code>[ -> ]</code>

=== Objects ===

An object is a container containing additional variables (see [[#Variables|below]] for further explanation of variables) which are not in the global scope. The ''dot operator'' can be used to evaluate a formula in the object's scope. For example, suppose ''u'' is a unit object referring to your leader, who is an Elvish Ranger who has taken 12 damage (thus has 30 hit points). Then <syntaxhighlight lang='wfl' inline>u.hitpoints</syntaxhighlight> will evaluate to the number 30. For a more advanced example, <syntaxhighlight lang='wfl' inline>u . (hitpoints < max_hitpoints - 10)</syntaxhighlight> will evaluate to true if the unit has taken more than 10 damage, which in this example, it has. (This could also be written <syntaxhighlight lang='wfl' inline>u.hitpoints < u.max_hitpoints - 10</syntaxhighlight> if you prefer; this enters the scope twice, instead of once, but the result is identical.)

Objects generally cannot be created directly by the code - they are created for you by the game when formulas are called in certain contexts. However, there are two types of object that ''can'' be created by your code. The first is the location object, which has variables ''x'' and ''y''; it can be created by the [[#loc|<code>loc()</code>]] function. The second is the map pair object, which is returned (or used internally) by several of the built-in functions and has variables ''key'' and ''value''.

==== Documentation of some common objects ====

There are a number of common objects that are given as the context object for formulas throughout the engine. Not all of these will be available in all formulas, but many of them are available in more than one formula. To learn what objects are available in a given location, see the WML documentation of that location.

* [[StandardUnitFilter#Wesnoth_Formula_Language|unit objects]]
* [[FilterWML#Filtering_Weapons|weapon objects]]
* [[StandardLocationFilter#Wesnoth_Formula_Language|terrain objects]]
* [[StandardSideFilter#Wesnoth_Formula_Language|side objects]]
* [[ImagePathFunctions#CHAN:_General function|pixel objects]]
* [[ConditionalActionsWML#.5Bvariable.5D|WML objects]]
* [[EventWML#filter_formula|game state objects]]

=== Other Types and Operators ===

There is one other basic type in WFL - the null type, which is used to mean "no value". It will be returned if you attempt to perform an invalid operation, such as dividing a string. It is also returned by the built-in <code>null()</code> function, which allows you to test if a value is null by writing <syntaxhighlight lang='wfl' inline>value = null()</syntaxhighlight>.

The logical operators <code>and</code> and <code>or</code> can be used to connect conditional expressions, and the unary operator <code>not</code> negates them. Note that <code>or</code> is inclusive - <syntaxhighlight lang='wfl' inline>A or B</syntaxhighlight> is false only if both ''A'' and ''B'' are false. These operators consider <code>0</code> or null to be false, while all other values count as true. The [[#if|<code>if()</code>]] function also follows the same rules to determine whether a value is true or false.

'''Note:''' Programmers familiar with other languages may occasionally be surprised by the fact that <code>and</code> and <code>or</code> do not short-circuit (which would mean that they will never evaluate their second argument if they can know their result solely from the first argument). This should not be a problem in general formula usage, since functions do not have side-effects, but it could make a difference when using the debug functions.

=== Operator Precedence ===

The precedence of various operators is, more or less, what you'd expect - you can write something like <syntaxhighlight lang='wfl' inline>a + b * 2 <= 5 and n - m / 4 > 7</syntaxhighlight> and the engine will do what you expect - first multiplication and division, then addition and subtraction, then comparison, and finally logical conjunction. The only thing to watch out for is when chaining exponentiation - all operators are left associative, so <syntaxhighlight lang='wfl' inline>a ^ b ^ c</syntaxhighlight> will be evaluated as <syntaxhighlight lang='wfl' inline>(a ^ b) ^ c</syntaxhighlight> instead of <syntaxhighlight lang='wfl' inline>a ^ (b ^ c)</syntaxhighlight> like you would expect. {{DevFeature1.13|5}} This has been fixed - exponentiation is now right-associative.

The full precedence list is as follows, from lowest to highest; operators on the same line have equal precedence.

# <code>not</code>
# <code>where</code> clauses
# <code>or</code>
# <code>and</code>
# Comparison operators <code>= != < <= > >= in</code>
# Range-generating operator <code>~</code>
# Additive operators <code>+ - ..</code>
# Multiplicative operators <code>* /</code>
# Modulus <code>%</code>
# Exponentiation <code>^</code>
# Dice operator <code>d</code>
# Dot operator <code>.</code>

== Functions ==

WFL is a ''functional'' language, so of course it has functions. There is a large library of [[#Core Functions|built-in functions]], and you can also [[#Defining Functions|define your own]].

Calling a function is simple, and works exactly how you would expect if you've worked with functions in a mathematical context: <syntaxhighlight lang=wfl inline>clamp(value, 0, 21)</syntaxhighlight>

Being a functional language, WFL does not have conditional or looping statements. Instead, these are provided by functions. For a simple conditional, you can use the <tt>if</tt> function, as in the following example:

<syntaxhighlight lang=wfl>
if(hitpoints > 37,
max_hitpoints / 2,
hitpoints - 3
)
</syntaxhighlight>

Similarly, looping is done via functions. There are several built-in higher-order functions that can be used to iterate over lists and maps, such as <tt>filter</tt>, <tt>choose</tt>, <tt>map</tt>, and <tt>reduce</tt>. See the corresponding function definitions for more information.

== Variables ==

Formulas may have a variety of variables, depending on the context in which they are evaluated. A string substitution formula like <code>$(3 + 5)</code> has no variables, but a [[StandardUnitFilter|unit filter]] formula has variables such as <code>hitpoints</code> and <code>max_hitpoints</code> which contain various properties of the unit being tested (the same unit which is also referred to in variable substitution as <code>$this_unit</code>). The special variable <code>self</code> typically refers to the "global context" - in the case of a unit filter formula, the unit itself. This means for example that <code>self.hitpoints</code> and <code>hitpoints</code> are equivalent when used in a unit filter formula. In a string substitution formula (the <code>$(formula)</code> syntax), <code>self</code> is null. Because of this, you should prefer not to use the substitution syntax in places where formulas are specifically supported.

A formula may declare additional variables using a <code>where</code> clause. This assigns a meaning to any unknown variables in the preceding formula. The general syntax is:

<formula> where <variable> = <value> [, <variable> = value ...]

This functions similarly to an operator, so if desired, you could have multiple where clauses in a single formula. Note that all variables in WFL are read-only - they are variables because they may have different values depending on the context in which the formula is evaluated, but for a given context, they are constant. A variable that has not been assigned a value is considered to have a value of null. Variables are lazily-evaluated - if a where clause declares a variable that is never used, the expression assigned to it will never be evaluated. (This only really matters if it contains a call to a debug function.)

Variable names can contain letters and underscores only. In particular, they cannot contain digits. Also, names are case-sensitive, so ''y'' and ''Y'' refer to two different variables. The following names are reserved and cannot be used for the name of a variable or function:

* <tt>d</tt> - dice operator
* <tt>or</tt> - logical operator
* <tt>in</tt> - containment operator
* <tt>def</tt> - defines a function
* <tt>and</tt> - logical operator
* <tt>not</tt> - logical operator
* <tt>fai</tt> - deprecated synonym of <tt>wfl</tt>
* <tt>wfl</tt> - declares filename
* <tt>where</tt> - declares variables
* <tt>faiend</tt> - deprecated synonym of <tt>wflend</tt>
* <tt>wflend</tt> - closes file scope
* <tt>functions</tt> - lists all defined functions

== Comments ==

Sometimes with particularly complicated formulas, it may be useful to document what's going on inline. Of course, you can use WML comments to do this, but in some cases it may be useful to put some comments in the middle of the formula. This is easily done - simply enclose them in <code>#</code> characters, like this:

<syntaxhighlight lang='wfl'>
#This is a Wesnoth Formula Language comment.#
</syntaxhighlight>

Note the final <code>#</code> - unlike WML, WFL requires this to indicate where the comment ends.

== Defining Functions ==

There are several predefined functions in the Wesnoth Formula Language, and if these are not enough, it is possible to define your own functions. The special variable <syntaxhighlight lang='wfl' inline>functions</syntaxhighlight> always evaluates to a list of all known function names. This is mainly useful only as a debugging tool, though.

To define a function, you use the <code>def</code> keyword. For example:

<syntaxhighlight lang='wfl'>
def sgn(x) if(x < 0, -1, x > 0, 1, 0);
</syntaxhighlight>

This defines a function called <code>sgn</code> which returns the sign of the input number. The semicolon marks the end of the function. It's optional if there's nothing else following the function, but in practice this will very rarely be the case.

Function names have the same limitation as variable names – they can contain only letters and underscores, and cannot contain digits.

You can select one of the function's arguments to be the "default" argument. If an object is passed to the default argument, then any attributes of that object are directly accessible in the global scope. For example:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u*) hitpoints < max_hitpoints / 2;
</syntaxhighlight>

This function takes a unit and returns 1 if it is at less than half hitpoints. The <code>*</code> indicates the default argument, without which it would instead have to be defined like this:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u) u.hitpoints < u.max_hitpoints / 2;
</syntaxhighlight>

It's important to remember that the function body has access to no variables other than its parameters. For example, the following function would not work (in a unit filter context) even though the unit variable is defined:

<syntaxhighlight lang='wfl'>
def endangers_me(u) distance_between(u.loc, unit.loc) < u.moves;
</syntaxhighlight>

This is because the body of the function can't see the unit variable. To make this work, you would need to pass in unit as an additional parameter.

'''Note: Prior to 1.14, function definitions only work in AI code and GUI2 code.'''

== Where to Use Formulas ==

Formulas can only be used in specific attributes in WML. The documentation of a WML tag will note which keys can have a formula placed in them. Some common examples include [[FilterWML|filters]], [[GUIToolkit|GUI2 dialogs]], and [[AbilitiesWML|unit abilities]]. Another example is the [[VariablesWML#Variable_Substitution|<code>$(formula)</code> substitution]] syntax, which allows the use of formulas wherever variables are parsed.

When using a formula in WML (other than in a substitution, which is usually part of a longer already-quoted passage), it is highly recommended to place double quotes around the formula, to avoid ambiguity between the WML and WFL parsers. The double angle quotes are also acceptable for this purpose. If you don't quote your formulas, there are two issues you could run into:

# WML uses the <code>+</code> operator to represent concatenation of strings, as well as line continuation. Because of this, an unquoted <code>+</code> will be ''removed'', likely causing the WFL formula to fail to compile.
# Unquoted WML text has the whitespace collapsed. If using WFL strings where whitespace is significant, this can result in surprises. For example, the formula <syntaxhighlight lang=wfl inline>length('One Two Three')</syntaxhighlight> would return 13 instead of the expected 19 if double quotes are not placed around the formula.

Some attributes in WML ''require'' a formula, which means that anything placed in the attribute will always be considered to be a formula. In this case, the formula doesn't need to be enclosed in parentheses – just the double quotes will suffice. However, there are also attributes that take an ''optional'' formula. These are most common in GUI2, but are also found in other places. In such attributes, the formula ''must'' be enclosed in parentheses. Failure to do so will result in it being parsed as just a straight value. As a general guideline, if the attribute key contains the word "formula", it is usually required to be a formula, whereas attributes with optional formulas do ''not'' contain the word "formula" in the key.

'''Note''': Do ''not'' use a <code>$</code> to introduce a formula. The <code>$</code> is not part of WFL syntax. It introduces a ''substitution'', a concept which is covered in more detail at [[VariablesWML#Variable Substitution]]. Although WFL can be used ''inside'' a substitution, a substitution itself is not WFL, and you should ''never'' use a <code>$</code> in WFL. However, in practice, substitutions and WFL are often used together – as substitution is processed first, you may see WFL formulas that appear to contain a <code>$</code> inside them. This is ''not'' part of the WFL – it is more like a macro substitution to be carried out before the formula runs. So, of course, it will only work in places that support ''both'' WFL and substitution.

== Files ==

{{DevFeature1.13|5}}

On occasion, you may find yourself working with formulas complex enough to split them out into a separate file. The formula engine normally assumes that it is executing inline code and reports errors accordingly, but you can tell it to enter a file scope using the special <code>wfl</code> keyword. The convention is to frame your code, so that any file looks like this:

<syntaxhighlight lang='wfl'>
wfl 'filename.wfl'

# Put whatever code you need here, possibly including function definitions. #

wflend
</syntaxhighlight>

The matching <code>wflend</code> is required.

'''Note:''' This functionality was available prior to 1.13.5 using keywords <code>fai</code> and <code>faiend</code>. {{DevFeature1.19|14}} As of 1.19.14, support for the <code>fai</code> and <code>faiend</code> keywords has been removed.

These directives have no effect on the formula code itself. They only change how error messages are reported if something goes wrong. Files using these directives are usually included using the WML preprocessor, though they could also be loaded in Lua with [[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]].

== Core Functions ==

Many of the core functions exhibit two features that (as of 1.13.4) cannot be used in user-defined functions. The first is the ability to accept a varying number of arguments - some core functions accept any number of arguments, while others have a few optional arguments. The second is that arguments are lazily-evaluated, and in some cases some arguments will not be evaluated at all, while others may be evaluated multiple times with different variable values. The description of each function will explain how and when its arguments are evaluated.

Most of the core functions can be used from any formula. However, there are some that are only available in formulas that have access to the game state. The following formulas have access to the game state and can use those functions:

* Formulas used in [[FilterWML]]
* Formulas used in [[AbilitiesWML]]
* <tt>filter_formula</tt> in [[EventWML#filter_formula|EventWML]]
* Formulas evaluated from the formula console (accessed by pressing F)

The following formulas do not have access to the game state and cannot use those functions:

* Formulas used in [[GUI2]]
* [[SyntaxWML#formula_substitution|Substitution]] formulas using <tt>$(...)</tt>
* [[ImagePathFunctions#CHAN: General function|IPF]] formulas used in <tt>~CHAN()</tt> or <tt>~ALPHA()</tt>
* Formulas compiled from [[LuaAPI/wesnoth#wesnoth.compile_formula|Lua]]

=== Conditional Functions ===

There are two functions which return one of their input values based on some condition - the <code>if</code> function, and the <code>switch</code> function. Both evaluate only as many parameters as is needed to determine which value to return. In particular, parameters that are neither returned nor part of the condition will never be evaluated.

==== if ====

* if(''condition'', ''if true'' [, ''condition 2'', ''if true 2'', ...] [, ''otherwise''])

This function first evaluates the ''condition'', which is a formula. If it evaluates to true, then the function evaluates and returns the ''if true'' parameter; otherwise, it tries the next condition (if any) with the same result. If none of the conditions evaluate to true, then it returns the ''otherwise'' parameter if present, or <code>null()</code> otherwise.

For instance, an event that is triggered by Wolf Riders on the first turn, and Orcish Grunts thereafter might have a unit filter formula that looks like this:

<syntaxhighlight lang='wfl'>
if(turn_number = 1, type = 'Wolf Rider', type = 'Orcish Grunt))
</syntaxhighlight>

==== switch ====

* switch(''formula'', ''value 1'', ''outcome 1'' [, ... , ''value N'', ''outcome N''] [, ''default outcome''])

The switch function first evaluates the input ''formula'', and then checks if it is equal to any of the specified ''values''. If matching value is found, the ''outcome'' assigned to it is returned; if not, then function returns either ''default outcome'' (if specified) or null.

=== Numeric Functions ===

Several basic math functions are available. These generally work equally on integer and decimal values.

==== abs ====

* abs(''number'')

Returns the absolute value of an input number; for example

<syntaxhighlight lang='wfl'>
abs( -5 )
</syntaxhighlight>

will return 5.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== acos ====

{{DevFeature1.13|5}}

* acos(''number'')

Returns the arccosine of the input number, in degrees.

==== asin ====

{{DevFeature1.13|5}}

* asin(''number'')

Returns the arcsine of the input number, in degrees.

==== atan ====

{{DevFeature1.13|5}}

* atan(''number'')

Returns the arctangent of the input number, in degrees.
==== as_decimal ====

* as_decimal(''number'')

Ensures that the number is a decimal rather than an integer; useful if you're dividing two unknown values and want to ensure that the result is a decimal.

==== cbrt ====

{{DevFeature1.13|5}}

* cbrt(''number'')

Returns the cube root of the input number. This is better than using the exponentiation operator, because it will give the correct result for negative numbers.

==== ceil ====

* ceil(''number'')

Returns the ceiling of the specified number, ie rounding it up to the nearest integer.

==== clamp ====

{{DevFeature1.17|0}}

* clamp(''number'', ''min'', ''max'')

Combines min and max into a single call. If ''number'' is less than ''min'', returns ''min''; if it's greater than ''max'', returns ''max''. Otherwise, returns ''number''.

==== cos ====

* cos(''angle'')

Returns the cosine of the given angle, which is specified in degrees.

==== exp ====

{{DevFeature1.13|5}}

* exp(''number'')

Returns the exponential of the input number, which is the constant ''e'' raised to the specified power.

==== floor ====

* floor(''number'')

Returns the floor of the specified number, ie rounding it down to the nearest integer.

==== frac ====

{{DevFeature1.13|5}}

* frac(''number'')

Returns the fractional part of the specified number.

==== hypot ====

{{DevFeature1.13|5}}

* hypot(''x'', ''y'')

Returns the hypoteneuse length of a triangle with sides ''x'' and ''y''.

==== lerp ====

{{DevFeature1.17|0}}

* lerp(''min'', ''max'', ''fraction'')

Returns a linear interpolation between ''min'' and ''max'' according to the specified ''fraction''.

==== lerp_index ====

{{DevFeature1.19|4}}

* lerp_index(''list'', ''ratio'')

Returns the element of the list that is closest to being at the specified ratio of the list's length.

'''Example''': <syntaxhighlight lang=wfl inline>lerp_index([1, 12, 32, 10], 0.26])</syntaxhighlight> returns 12.

==== log ====

{{DevFeature1.13|5}}

* log(''number'', [, ''base''])

Returns the logarithm of the input number. If ''base'' is omitted, it returns the natural logarithm; otherwise, the logarithm to the specified base.

==== max ====

* max(''list of numbers'')

Returns the largest number from the list. For example:

<syntaxhighlight lang='wfl'>
max([2, 8, -10, 3])
</syntaxhighlight>

will return <code>8</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== min ====

* min(''list of numbers'')

Returns the smallest number from the list. For example:

<syntaxhighlight lang='wfl'>
min( [ 3, 7, -2, 6] )
</syntaxhighlight>

will return <code>-2</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== pi ====

{{DevFeature1.13|5}}

* pi()

Returns pi.

==== root ====

{{DevFeature1.13|5}}

* root(''number'', ''base'')

Returns the root of the input number, to the specified base. This is better than using the exponentiation operator, because it will give the correct result for negative numbers and odd bases (for example, the fifth root of -32, which is -2).

==== round ====

* round(''number'')

Returns the specified number rounded to the nearest integer.

==== sgn ====

{{DevFeature1.13|5}}

* sgn(''number'')

Returns the sign of the number, ie -1 if it is negative, 1 if it is positive, and 0 if it is zero.

==== sin ====

* sin(''angle'')

Returns the sine of the given angle, which is specified in degrees.

==== sqrt ====

{{DevFeature1.13|5}}

* sqrt(''number'')

Returns the square root of the input number.

==== sum ====

* sum(''list of numbers'')

This function evaluates to the sum of the numbers in the ''list of numbers''. For example:

<syntaxhighlight lang='wfl'>
sum([ 2, 5, 8])
</syntaxhighlight>

returns <code>15</code>, and:

<syntaxhighlight lang='wfl'>
sum(map(my_units, max_hitpoints - hitpoints))
</syntaxhighlight>

finds the total damage your units have taken.

==== tan ====

{{DevFeature1.13|5}}

* tan(''number'')

Returns the tangent of the given angle, which is specified in degrees.

==== trunc ====

{{DevFeature1.13|5}}

* trunc(''number'')

Returns the truncation of the specified number, ie rounding it towards zero. This is different from floor when applied to negative numbers - floor(-7.5) gives -8, but trunc(-7.5) gives -7.

==== wave ====

* wave(''number'')

Given a numeric value V, this returns:

sin(2*pi*V)

=== String Functions ===

There are a few useful functions for manipulating strings.

==== concatenate ====

* concatenate(''value1''[, ''value2'', ...])

Converts each of its arguments to a string, and concatenates the result together into a single string.

==== contains_string ====

* contains_string(''string'', ''search_string'')

Returns 1 if ''search_string'' can be found within ''string'' (as a substring), 0 otherwise. For example:

<syntaxhighlight lang='wfl'>
contains_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>1</code>.

==== length ====

* length(''string'')

Returns the length of the input string.

==== ends_with ====

{{DevFeature1.19|4}}

* ends_with(''string'', ''suffix'')

Determines whether the ''string'' ends with the specified ''suffix''.

==== find_string ====

{{DevFeature1.13|5}}

* find_string(''string'', ''search_string'')

Returns the index at which ''search_string'' starts within ''string'' (as a substring), or -1 if it is not found. For example:

<syntaxhighlight lang='wfl'>
find_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>4</code>.

==== replace ====

{{DevFeature1.13|5}}

* replace(''string'', ''offset'', [''size'',] ''replacement'')

Returns a new string obtained by replacing a portion of the input ''string'' with the contents of the ''replacement'' string. The ''offset'' and ''size'' work the same as for <code>substring</code>. Examples:

<syntaxhighlight lang='wfl'>
replace('The quick brown fox jumps over the lazy dog!', 4, 5, 'dumb')
replace('The quick brown fox jumps over the lazy dog!', -9, 4, 'sleeping')
replace('The quick brown fox jumps over the lazy dog!', -9, 'brook!')
replace('The quick brown fox jumps over the lazy dog!', -6, -4, 'yellow')
</syntaxhighlight>

return the following strings:

'The dumb brown fox jumps over the lazy dog!'
'The quick brown fox jumps over the sleeping dog!'
'The quick brown fox jumps over the brook!'
'The quick brown fox jumps over the yellow dog!'

==== replace_all ====

{{DevFeature1.19|4}}

* replace_all(''string'', ''match'', ''replacement'')

Returns a copy of ''string'' with all occurrences of ''match'' replaced by ''replacement''.

==== starts_with ====

{{DevFeature1.19|4}}

* starts_with(''string'', ''prefix'')

Determines whether the ''string'' begins with the specified ''prefix''.

==== substring ====

* substring(''string'', ''offset''[, ''size''])

Extracts a substring from the given input string. The ''offset'' specifies the first character to extract; the first character is <code>0</code>, and negative values count from the end, so the last character is <code>-1</code>. If specified, the ''size'' indicates the total number of characters to extract; it cannot be negative. If omitted, all characters from the ''offset'' to the end of the string are returned. For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', 4, 5)
substring('The quick brown fox jumps over the lazy dog!', -9, 4)
substring('The quick brown fox jumps over the lazy dog!', -9)
</syntaxhighlight>

return <code>'quick'</code>, <code>'lazy'</code>, and <code>'lazy dog!'</code> respectively.

{{DevFeature1.13|5}} The ''size'' can now be negative. This means to count backwards from the given ''offset'' (but always including the given offset, so a ''size'' of -1 gives the same result as 1). For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', -6, -4)
</syntaxhighlight>

returns <code>'lazy'</code>.

=== List and Map Functions ===

This section contains functions that directly manipulate a map or list.

==== head ====

* head(''list'' [, ''count''])

Returns the first item from the ''list''; for example

<syntaxhighlight lang='wfl'>
head([5, 7, 9])
</syntaxhighlight>

returns <code>5</code>, and

<syntaxhighlight lang='wfl'>
head( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Orc'</code>.

{{DevFeature1.13|5}} If a second argument is given, it returns a list containing the first ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>head(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>head(L,1)</syntaxhighlight> - the former returns the first element, while the latter returns a list containing only the first element.

==== index_of ====

* index_of(''value'', ''list'')

This function will return the first index where ''value'' can be found in the input ''list''. It will return -1 if the value is not found in the ''list'.

==== keys ====

* keys(''map'')

Extracts the key values from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
keys(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

['Elvish Fighter', 'Elvish Archer']

==== size ====

* size(''list'')

This function returns the number of elements in the ''list''.

For example, <syntaxhighlight lang='wfl' inline>size([5, 7, 9])</syntaxhighlight> returns <code>3</code> and <syntaxhighlight lang='wfl' inline>size(['Archer', 'Fighter'])</syntaxhighlight> returns <code>2</code>.

==== sort ====

* sort(''list'', ''formula'')

This function evaluates to a result list sorted according to the comparison ''formula'' for each item <code>a</code> and its successor <code>b</code>. For instance, sorting units according to hitpoints would be done by:

<syntaxhighlight lang='wfl'>
sort(my_units, a.hitpoints > b.hitpoints)
</syntaxhighlight>

To sort them in the reverse order, simply use <code><</code> instead of <code>></code>.

==== tail ====

{{DevFeature1.13|5}}

* tail(''list'' [, ''count''])

Returns the last item from the ''list''; for example

<syntaxhighlight lang='wfl'>
tail([5, 7, 9])
</syntaxhighlight>

returns <code>9</code>, and

<syntaxhighlight lang='wfl'>
tail( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Human'</code>.

If a second argument is given, it returns a list containing the last ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>tail(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>tail(L,1)</syntaxhighlight> - the former returns the last element, while the latter returns a list containing only the last element.

==== tolist ====

* tolist(''map'')

This function takes a map and return a list of key-value pair objects. For example:

<syntaxhighlight lang='wfl'>
tolist(['Elf' -> 10, 'Dwarf' -> 20])
</syntaxhighlight>

will return:

[{key->'Elf',value->10}, {key->'Dwarf',value->20}]

==== tomap ====

* tomap(''list A'' [, ''list B''])

This function takes one or two ''lists'' as input and returns a map. If only one list is specified, then the function will evaluate this list, count how many similar elements are found within the list, and return a map with keys being these elements, and values being a number representing how many of them the list contains. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf', 'elf', 'elf', 'human', 'human'])
</syntaxhighlight>

will return:

['elf' -> 3, 'dwarf' -> 1, 'human' -> 2]

{{DevFeature1.13|5}} However, if all the elements are key-value pairs such as those created by ''pair'' or ''tolist'', then this function will invert the effect of ''tolist'' and return the original map which would have produced the input list as output when passed to ''tolist''. If only some elements are key-value pairs, those elements will be directly converted into key-value pairs in the resulting map, while other values will be treated as described above.

If two lists are specified, then the elements of the first one will be used as a keys, and the elements of the second one as a values, when creating an output map. Note that these input lists must be of the same length. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf' ], [10, 20])
</syntaxhighlight>

will result in:

['elf' -> 10, 'dwarf' -> 20]

==== values ====

* values(''map'')

Extracts the values assigned to keys from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
values(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

[50, 60]

=== List-processing Functions ===

This section covers functions that operate on maps or lists by applying one or more formulas in succession to each element. Most return another map or list, <code>reduce</code> instead combines all the elements into a single result.

==== choose ====

* choose(''input'', [''self_name'',] ''formula'')

This function evaluates ''formula'' for each item in the ''input'' (which can be a list or a map). It will return the first item to which ''formula'' gave the highest value. For example:

<syntaxhighlight lang='wfl'>
choose(my_units, level)
</syntaxhighlight>

gives back the unit with the highest level.

The implicit input when evaluating a mapping/filtering function's ''formula'' component will be that specific item under evaluation (in this example one of "my_units"), and it can be explicitly referenced as <code>self</code> when necessary. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

When evaluating a map, we can reference each key by <code>key</code> and each value by <code>value</code>. In this case, the <code>self</code> variable is this key-value pair. For example:

<syntaxhighlight lang='wfl'>
choose(['elf' -> 10, 'dwarf' -> 20 ], value)
</syntaxhighlight>

will return a key-value pair

{key->'dwarf', value->20}

The curly braces are used in output to indicate that this is an object, not a map. It is not valid WFL syntax.

==== filter ====

* filter(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map). It will evaluate to a list or map which only contains items that the ''formula'' was true for. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

<syntaxhighlight lang='wfl'>
filter(my_units, hitpoints < max_hitpoints)
</syntaxhighlight>

will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

==== find ====

* find(''input'', [''self_name'',] ''formula'')

This function will run <formula> on each item in the <input> (which can be a list or a map) and will return the first item for which <formula> was true. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. For example:

<syntaxhighlight lang='wfl'>
find(units, type = 'Elvish Archer' )
</syntaxhighlight>

will return the first unit of type 'Elvish Archer'.

==== map ====

* map(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map), and evaluate to a new list or map or a map, which contains the same number of items as in ''input'', with the formulas run on each item. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. When run on a map, the resulting map has the same keys as the input map, but with the values updated to the results of the ''formula''. For example:

<syntaxhighlight lang='wfl'>
map([10,20], self*self)
</syntaxhighlight>

and

<syntaxhighlight lang='wfl'>
map([10,20], 'value', value*value)
</syntaxhighlight>

will both result in [100, 400]. The formula:

<syntaxhighlight lang='wfl'>
map(my_units, hitpoints)
</syntaxhighlight>

will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

<syntaxhighlight lang='wfl'>
map(['elf' -> 10, 'dwarf' -> 20 ], value*2)
</syntaxhighlight>

The above will produce ['elf' -> 20, 'dwarf' -> 40]. Note that in case of a map data type, the <code>map</code> function can only modify the value.

<syntaxhighlight lang='wfl'>
map(tomap([3,5,8,8]), value+key*100)
</syntaxhighlight>

The above will produce <code>[3 -> 301, 5 -> 502, 8 -> 801]</code>. This can be used to take a list and make a map containing pairs <code>[element_from_that_list -> f(element_from_that_list,number_of_repetitions_of_that_element_in_that_list)]</code> where <code>f</code> is an arbitrary function.

==== reduce ====

* reduce(''list'', [''identity'', ] ''formula'')

This function will run the ''formula'' on the first and second members of the ''list'', then on the result and the third member and so on until the list is depleted. The final result is then returned. The two variables used in the ''formula'' are always 'a' and 'b'.

For example, <syntaxhighlight lang='wfl' inline>reduce([1,2,3,4], a+b)</syntaxhighlight> returns <code>10</code> and <syntaxhighlight lang='wfl' inline>reduce([9,4,8,2], 10*a+b)</syntaxhighlight> returns <code>9482</code>.

{{DevFeature1.13|5}} The new ''identity'' argument specifies the starting value (which is null or 0 by default). If ''list'' is empty, then ''identity'' is returned. Otherwise, the list will be considered as if ''identity'' were an extra first element. For example, to calculate the product of a list of numbers, you might do something like this:
<syntaxhighlight lang='wfl'>
reduce(your_list, 1, a * b)
</syntaxhighlight>

This will return 1 if the list is empty, as expected - the product of no numbers is 1. If the list is not empty, adding 1 to the list will have no effect, since it is the multiplicative identity.

==== take_while ====

{{DevFeature1.13|5}}

* take_while(''list'', ''formula'')

Evaluates the ''formula'' for each element of the ''list'' until it finds one for which it evaluates to false, then returns a list of all elements up to but not including that element. For example:

<syntaxhighlight lang='wfl'>
take_while([1,5,3,6,3,7,9,5,6,4,12,2,53,2,1], self < 10)
</syntaxhighlight>

returns the list <code>[1,5,3,6,3,7,9,5,6,4]</code>.

==== zip ====

{{DevFeature1.13|5}}

* zip(''list1'', ... , ''listN'')
* zip(''list of lists'')

Takes a list of lists and generates a new list of lists such that list ''n'' contains element ''n'' of each of the original lists, in order. If the lists are not all of the same length, it treats them as if they were padded on the end with null values so that they are all the length of the longest list.

<syntaxhighlight lang='wfl'>
zip([1,2,3],[4,5,6])
zip([1,4],[2,5],[3,6])
</syntaxhighlight>

return <code>[[1,4],[2,5],[3,6]]</code> and <code>[[1,2,3],[4,5,6]]</code>, respectively.

=== Location Functions ===

Functions for working with locations on a hex map.

==== adjacent_locs ====

{{DevFeature1.13|9}}

* adjacent_locs(''center'')

Returns a list of all locations adjacent to the specified location. When called from a formula with access to the game state, it automatically excludes locations that don't exist on the map. Otherwise, it operates as if on an infinite map. This means you should generally not expect the returned list to contain exactly 6 elements.

==== are_adjacent ====

{{DevFeature1.13|9}}

* are_adjacent(''loc1'', ''loc2'')

Check if two locations are adjacent. Returns 1 (true) or 0 (false).

==== direction_from ====

{{DevFeature1.13|9}}

* direction_from(''start'', ''direction'', [''distance''])

Returns the hex reached by travelling in the specified direction from a starting hex for a certain distance (default 1 hex).

==== distance_between ====

{{DevFeature1.13|5}}

* distance_between(''start'', ''end'')

Returns the distance between the locations ''start'' and ''end'', which must be location objects such as those created by <code>loc()</code>.

'''Note:''' This function was already available in FormulaAI prior to 1.13.5; however, from 1.13.5 onward it is available to all formulas.

==== loc ====

* loc(''x'', ''y'')

Creates and returns a location object with the specified coordinates. If assigned to a variable ''pos'' (eg with a <code>where</code> clause), the individual coordinates can be accessed as <code>pos.x</code> and <code>pos.y</code>.

==== locations_in_radius ====

{{DevFeature1.13|9}}

* locations_in_radius(''center'', ''radius'')

Returns a list of all locations within a given radius of the specified center hex.
Only locations on the map will be returned.

==== nearest_loc ====

{{DevFeature1.19|14}}

* nearest_loc(''origin'', ''locations'')

Returns the location in the given list closest to ''origin''. All arguments must be location objects such as those created by <code>loc()</code>.

'''Note:''' This function was already available in FormulaAI prior to 1.19.14; however, from 1.19.14 onward it is available to all formulas.

==== relative_dir ====

{{DevFeature1.13|9}}

* relative_dir(''loc1'', ''loc2'')

Returns the direction you need to travel to progress from one location to another. The returned location is one of the six possible directions on the Wesnoth hex map, or an empty string if both locations are the same.

==== rotate_loc_around ====

{{DevFeature1.13|9}} but returns wrong result until {{DevFeature1.19|2}}

* rotate_loc_around(''center'', ''loc'', ''angle'')

Rotates a location around a given center to produce a new location. The angle is an integer between -6 and 6, which can be understood as a multiple of 60 degrees.

=== Miscellaneous Functions ===

Some functions really don't fit into any category. They are all listed here.

==== null ====

* null([''arguments''])

Evaluates each of its arguments (if any) in order, then returns null. Since formulas generally do not have side-effects, there is usually little point in specifying any arguments, but it could be thought of as a way to "comment out" a section of the formula while ensuring it remains syntactically valid.

==== pair ====

{{DevFeature1.13|5}}

* pair(''key'', ''value'')

Creates a key-value pair object, the same as those created by the ''tolist'' function.

==== reverse ====

{{DevFeature1.13|5}}

* reverse(''string or list'')

Returns the input string or list backwards.

==== type ====

{{DevFeature1.13|5}}

* type(''anything'')

Returns the type of its input as a string. Possible results are:

* <code>'integer'</code>
* <code>'decimal'</code>
* <code>'string'</code>
* <code>'list'</code>
* <code>'map'</code>
* <code>'null'</code>
* <code>'object'</code>

==== get_palette ====

{{DevFeature1.19|4}}

* get_palette(''name'')

Returns a list of colours that make up the named palette. Palettes are defined by a '''[color_palette]''' tag, usually in the [[GameConfigWML#Color_Palettes|game config]]. The palettes defined in core Wesnoth are '''magenta''', '''flag_green''', and '''ellipse_red'''. In addition to defined palettes, several hard-coded palettes are available by name. They are '''red_green_scale''', '''red_green_scale_text''', '''blue_white_scale''', and '''blue_white_scale_text'''. These are also defined in the game config, but not with a '''[color_palette]''' tag.

=== Debugging Functions ===

There are also a few functions that can be useful for debugging formulas, for example by displaying intermediate results to the screen. Note that this breaks the general rule that functions do not have side-effects.

==== debug ====

* debug([''formula''])

Starts a GUI formula debugger when evaluating a formula. It takes a formula, evaluates it and returns the result unchanged. '''Note:''' this does not appear to work in 1.13.3.

{{DevFeature1.13|5}} The formula allows you to step through the formula one operation at a time, viewing the current stack and execution trace. As of 1.13.5, you need to enable [[CommandMode|debug mode]] to use the debugger; otherwise, it will simply be skipped.

==== debug_print ====

'''you need to enable formula log (--log-info='scripting/formula') to see the result of this call'''

* debug_print([''explanation'' ,] ''formula'' )

This function can be used for debugging a formula. It takes a ''formula'', writes its result to the console, and returns it unchanged. For example:

<syntaxhighlight lang='wfl'>
debug_print([1, 2, 3])
</syntaxhighlight>

will result in printing to the console

[1, 2, 3]

and returning the same.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_print'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_print('My array: ', [1, 2, 3])
</syntaxhighlight>

will write in the console:

My array: [1, 2, 3]

and return

[1, 2, 3]

==== debug_profile ====

* debug_profile(''formula'' [, ''explanation''])

Evaluates the formula 1000 times and prints (as with debug_print) a number indicating the average time required to evaluate the formula. Mainly intended for internal testing, but could occasionally be useful for people working with complicated formulas. The optional ''explanation'' argument is used in the same way as in debug_print.

==== debug_float ====

* debug_float(''location'', [''explanation'',] ''formula'' )

This function can be used for debugging a formula. It takes a formula, floats a label containing the result on the hex specified (in the same way damage is displayed) and returns it unchanged. Note that the ''location'' here is an object type; it can be created with the <code>[[#loc|loc()]]</code> function. For example:

<syntaxhighlight lang='wfl'>
debug_float(me.loc, me.id)
</syntaxhighlight>

will make a label containing the id of the unit ''me'' float over the unit.

Return value is also the unit id.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_float'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_float( me.loc, 'id: ', me.id )
</syntaxhighlight>

will float the following label

id: unit_id

and return the unit id.

==== dir ====

* dir(''object'')

This function return a list of all attributes in ''object''. For example:

<syntaxhighlight lang='wfl'>
dir(my_leader)
</syntaxhighlight>

will result in the following output:

[ 'x', 'y', 'loc', 'id', 'type', 'name', 'leader', 'undead', 'traits', 'attacks', 'abilities', 'hitpoints',
'max_hitpoints', 'experience', 'max_experience', 'level', 'total_movement', 'movement_left', 'attacks_left',
'side', 'states', 'cost', 'usage', 'vars']

This command is useful in the formula command line, to get information about the attributes of different types of data.

=== Game State Functions ===

These are functions that access the game state. Therefore, they are not available in all formulas, as described above.

==== base_tod_bonus ====

* base_tod_bonus([''loc'', [''turn'']])

Evaluates the base time-of-day bonus, excluding the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== chance_to_hit ====

* chance_to_hit(''unit'', ''location or terrain'')

Calculates the base chance for the unit to be hit if it moved to the given location or terrain. This is essentially the inverse of its defense. It is returned as an integer between 0 and 100.

==== defense_on ====

* defense_on(''unit'', ''location or terrain'')

Calculates the defense that the unit would have if it moved to the given location or terrain. It is returned as an integer between 0 and 100.

==== enemy_of ====

* enemy_of(''self'', ''other'')

Determines whether two units are enemies. Returns 1 (true) or 0 (false).

==== get_unit_type ====

* get_unit_type(''id'')

Returns an object describing the specified unit type, or null if no such unit type exists. A unit type object has many of the same keys as a unit, excluding those that are expected to change over time such as <tt>hitpoints</tt> or <tt>name</tt>.

==== jamming_cost ====

* jamming_cost(''unit or unit type'', ''location or terrain'')

Calculates the jamming cost for the unit to block vision on the given location terrain.

==== is_fogged ====

{{DevFeature1.19|14}}

* is_shrouded(''loc'', ''side_number''])

Returns whether the given location is currently fogged from the point of view of the given side.

==== is_shrouded ====

{{DevFeature1.19|14}}

* is_shrouded(''loc'', ''side_number''])

Returns whether the given location is currently shrouded from the point of view of the given side.

==== movement_cost ====

* movement_cost(''unit or unit type'', ''location or terrain'')

Calculates the movement cost for the unit to enter the given location or terrain.

==== resistance_on ====

* resistance_on(''unit'', ''location'', ''type'', [''attacker''])

Calculates the unit's resistance to the given damage type when standing on the specified location. If specified, the ''attacker'' parameter should be 1 to indicate that the unit is the attacker, or 0 to indicate that it is the defender, as this status can affect resistances. By default, it is assumed to be the defender.

This is returned not as the raw resistance set in WML, but the actual resistance that the player sees, so it ranges between -100 and 100.

==== tod_bonus ====

* tod_bonus([''loc'', [''turn'']])

Evaluates the final time-of-day bonus, accounting for the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== unit_at ====

* unit_at(''location'')

Returns the unit on the given location, or null if there is no unit there.

==== unit_tod_modifier ====

{{DevFeature1.19|14}}

* unit_tod_modifier(''unit'', [''loc''])

Returns the current combat damage modifier for the given unit for the current time of day, taking into account any abilities whose effects it is currently under (illuminates, for example). If no location is specified, the unit's current location will be used.

'''Note:''' Prior to 1.19.4, this function was available as the FormulaAI function ''timeofday_modifier''.

==== vision_cost ====

* vision_cost(''unit or unit type'', ''location or terrain'')

Calculates the vision cost for the unit to see through the given location or terrain.

=== Action Functions ===

These are special functions that represent an action to be executed. They don't actually execute the action, merely describe it – the action will be executed only after the formula has been fully evaluated.

Action functions can currently only be used in GUI2, in the '''actions''' key. This key must always evaluate to either an action or a list of actions.

==== set_var ====

* set_var(''name'', ''value'')

Sets a variable in the current '''self''' context to the specified value.

The result of this function is an object that has '''name''' and '''value''' keys with the passed-in values.

==== safe_call ====

* safe_call(''main'', ''backup'')

Tries to execute the ''main'' action first. If that fails, the ''backup'' action is executed instead.

The ''backup'' formula can access a special '''error''' object, which in turn contains two values:

* '''status''': A status code representing the type of error. Currently, the only possible status is 5001, which means the current context is immutable.
* '''object''': The action that failed to execute – in other words, the result of evaluating the ''main'' formula.

The result of this function is an object that has a '''main''' key that contains the result of evaluating the main formula.

Wesnoth Formula Language

2026-01-25T06:58:44Z

Celtic Minstrel: Document the two action functions.

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

The Wesnoth Formula Language is a functional language used to evaluate expressions within the game engine. It allows performing calculations that would not otherwise be possible using only WML. For example, to have an event trigger when a unit has less than half its hitpoints, you could write the following as the event's filter:

<syntaxhighlight lang=wml>
[filter]
formula = "(hitpoints < max_hitpoints / 2)"
[/filter]
</syntaxhighlight>

The '''formula''' key is a part of [[StandardUnitFilter]] that accepts a condition written as WFL. The part inside the quotes is the WFL formula. This example will evaluate to true if the unit's '''hitpoints''' are less than half its '''max_hitpoints'''.

== Data Types and Operators ==

Wesnoth Formula Language has seven basic data types – [[#Numbers|integers]], [[#Numbers|real numbers]] (usually called "decimals"), [[#Strings|strings]], [[#Lists|lists]], [[#Maps|maps]], [[#Objects|objects]], and [[#Other Types and Operators|null]].

=== Numbers ===

The most common use of WFL is for simple calculations involving numbers. For this, the standard arithmetic operators (<code>+ - * / %</code>) work as you would expect, performing addition, subtraction, multiplication, division, and remainder. {{DevFeature1.13|5}} The remainder operator even works on decimal numbers, producing the integer remainder of the division.

The only caveat to watch out for is that <code>/</code> rounds down when used on integers. For example, <syntaxhighlight lang='wfl' inline>5 / 2</syntaxhighlight> will evaluate to <code>2</code>. To avoid this, make sure at least one of the numbers includes a decimal point (or use [[#as_decimal|as_decimal]] if variables are involved) - <syntaxhighlight lang='wfl' inline>5.0 / 2</syntaxhighlight> will evaluate to <code>2.5</code>.

Note that WFL supports only three decimal places of precision for decimal numbers; beyond that it will still be rounded down. (So <syntaxhighlight lang='wfl' inline>1.0 / 16</syntaxhighlight> will evaluate to <code>0.062</code> instead of <code>0.0625</code>.) The <code>^</code> operator performs exponentiation (raising to a power) - for example, <syntaxhighlight lang='wfl' inline>2 ^ 3</syntaxhighlight> evaluates to <code>8</code>

You can also use the standard comparison operators (<code>= != < <= > >=</code>) on numbers. This is often useful in unit filters - for example, a formula of <syntaxhighlight lang='wfl' inline>hitpoints < max_hitpoints / 2</syntaxhighlight> will match only if the unit is at less than half health. Comparison operators return 1 for true and 0 for false; there is no boolean type. Comparing values of different types will always return 0, with one exception – comparing an integer and decimal number will work as expected.

One final numeric operator exists - the dice roll. The syntax <syntaxhighlight lang='wfl' inline>3d12</syntaxhighlight> will roll three 12-sided dice and return the sum of the results. Note however that this is not multiplayer-safe, so using it can and will produce OOS errors. {{DevFeature1.13|5}} The dice operator is now synced and should be safe for use in multiplayer contexts.

'''Note:''' {{DevFeature1.13|5}} Some numeric operations will return null instead of a number. This usually involves the exponentiation operator - for example, <syntaxhighlight lang='wfl' inline>(-2) ^ 0.5</syntaxhighlight> attempts to take the square root of -2, which doesn't exist, so it returns null to indicate this. Dividing by zero also returns null, as well as certain [[#Numeric Functions|math functions]] in appropriate circumstances.

=== Strings ===

WFL also supports strings, which must be enclosed in single quotes (<syntaxhighlight lang='wfl' inline>'like this'</syntaxhighlight>). The comparison operators (<code>= != < <= > >=</code>) also work on strings, performing lexicographical comparison (ie, alphabetical order). The comparison is case sensitive.

{{DevFeature1.13|5}}

Strings can be concatenated with the concatenation operator <code>..</code>. They also support interpolations enclosed in square brackets, the contents of which can be any valid formula. For example:

<syntaxhighlight lang='wfl'>
'Some text: [a + b]' where a = 12, b = 10
</syntaxhighlight>

results in the string <code>Some text: 22</code>. (The <code>where</code> operator is explained [[#Variables|below]].)

If you need to include a literal square bracket in a string, write <code>[(]</code> or <code>[)]</code>. For a literal single quote, you can write <code>[']</code>. For example:

<syntaxhighlight lang='wfl'>
'[(]It[']s bracketed![)]'
</syntaxhighlight>

results in the string <code>[It's bracketed!]</code>.

You can index the characters or words of a string with the following syntax:

<syntaxhighlight lang='wfl'>
'Hello World'.char[4]
'Hello World'.word[1]
</syntaxhighlight>

These return <code>o</code> and <code>World</code>, respectively. A third option is also available, <code>item</code>, which splits the string on commas but allows parentheses to prevent a portion of the string from being split up. For example:

<syntaxhighlight lang='wfl'>
'First Item,Second Item,Third Item'.item[1]
'a,b,(c,d,e),f,g'.item[2]
</syntaxhighlight>

These return <code>Second Item</code> and <code>(c,d,e)</code>, respectively. When not providing index, list is returned.

<syntaxhighlight lang='wfl'>
'Hello World'.char = ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd']
'Hello World'.word = ['Hello', 'World']
'a,b,(c,d,e),f,g'.item = ['a', 'b', '(c,d,e)', 'f', 'g']
</syntaxhighlight>

=== Lists ===

A list is a sequence of values represented as square brackets, [], surrounding a comma-separated list. For instance:

<syntaxhighlight lang='wfl'>
[ 1, 5, 'abc' ]
</syntaxhighlight>

The comparison operators work on lists, performing lexicographical comparison. A specific list index can be obtained with the indexing operator, like this: <syntaxhighlight lang='wfl' inline>my_list[index]</syntaxhighlight>. The first element of a list is numbered 0.

There are four ''vector operators'' (<code>.+ .- .* ./</code>) that perform entrywise operations on lists. For example, <syntaxhighlight lang='wfl' inline>[1,2,3] .+ [12,2,8]</syntaxhighlight> produces <code>[13,4,11]</code>. Both lists must be of the same length to use these operators, and of course, they must contain only numbers.

{{DevFeature1.13|5}}

A negative list index now counts from the end of the list - <code>-1</code> refers to the last element. You can check if an element exists in a list using the <code>in</code> operator. Lists can also be joined with the concatenation operator <code>..</code>, and sliced using the range operator <code>~</code>. In fact, the range operator produces a list of consecutive numbers, and in fact any list of numbers can be used to index a list - the result is to take the elements at the requested indices, in order. Some examples:

<syntaxhighlight lang='wfl'>
[1, 7, 'abc', 2.5, 'foobar', 127][1~3]
(10~20)[[0,-1]]
[1, 7, 'abc', 2.5, 'foobar', 127][[2,4]]
</syntaxhighlight>

These result in the following lists:

[7, 'abc', 2.5]
[10,20]
['abc', 'foobar']

=== Maps ===

A map is a sequence of key-value pairs. For example:

<syntaxhighlight lang='wfl'>
[12 -> 'Hello', [1,2] -> 9, 'abc' -> 1.5]
</syntaxhighlight>

The comparison operators work on maps. A specific element of a map can be obtained with the indexing operation. In the above example, the following conditions are all true (assuming the map is in a variable called <code>self</code>):

* <syntaxhighlight lang='wfl' inline>self[12] = 'Hello'</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self[[1,2]] = 9</syntaxhighlight>
* <syntaxhighlight lang='wfl' inline>self['abc'] = 1.5</syntaxhighlight>

{{DevFeature1.13|5}}

You can now use the <code>in</code> operator to test if a key exists in the map. You can also access string keys using the dot operator <code>.</code> as long as they are valid identifiers. (Valid identifiers contain letters and underscores only; no digits are permitted.)

Note that the selection indexing that lists use is ''not'' valid for maps - a list can be used as a key, after all.

Though it's rarely needed, it's possible to define an empty map with <code>[ -> ]</code>

=== Objects ===

An object is a container containing additional variables (see [[#Variables|below]] for further explanation of variables) which are not in the global scope. The ''dot operator'' can be used to evaluate a formula in the object's scope. For example, suppose ''u'' is a unit object referring to your leader, who is an Elvish Ranger who has taken 12 damage (thus has 30 hit points). Then <syntaxhighlight lang='wfl' inline>u.hitpoints</syntaxhighlight> will evaluate to the number 30. For a more advanced example, <syntaxhighlight lang='wfl' inline>u . (hitpoints < max_hitpoints - 10)</syntaxhighlight> will evaluate to true if the unit has taken more than 10 damage, which in this example, it has. (This could also be written <syntaxhighlight lang='wfl' inline>u.hitpoints < u.max_hitpoints - 10</syntaxhighlight> if you prefer; this enters the scope twice, instead of once, but the result is identical.)

Objects generally cannot be created directly by the code - they are created for you by the game when formulas are called in certain contexts. However, there are two types of object that ''can'' be created by your code. The first is the location object, which has variables ''x'' and ''y''; it can be created by the [[#loc|<code>loc()</code>]] function. The second is the map pair object, which is returned (or used internally) by several of the built-in functions and has variables ''key'' and ''value''.

==== Documentation of some common objects ====

There are a number of common objects that are given as the context object for formulas throughout the engine. Not all of these will be available in all formulas, but many of them are available in more than one formula. To learn what objects are available in a given location, see the WML documentation of that location.

* [[StandardUnitFilter#Wesnoth_Formula_Language|unit objects]]
* [[FilterWML#Filtering_Weapons|weapon objects]]
* [[StandardLocationFilter#Wesnoth_Formula_Language|terrain objects]]
* [[StandardSideFilter#Wesnoth_Formula_Language|side objects]]
* [[ImagePathFunctions#CHAN:_General function|pixel objects]]
* [[ConditionalActionsWML#.5Bvariable.5D|WML objects]]
* [[EventWML#filter_formula|game state objects]]

=== Other Types and Operators ===

There is one other basic type in WFL - the null type, which is used to mean "no value". It will be returned if you attempt to perform an invalid operation, such as dividing a string. It is also returned by the built-in <code>null()</code> function, which allows you to test if a value is null by writing <syntaxhighlight lang='wfl' inline>value = null()</syntaxhighlight>.

The logical operators <code>and</code> and <code>or</code> can be used to connect conditional expressions, and the unary operator <code>not</code> negates them. Note that <code>or</code> is inclusive - <syntaxhighlight lang='wfl' inline>A or B</syntaxhighlight> is false only if both ''A'' and ''B'' are false. These operators consider <code>0</code> or null to be false, while all other values count as true. The [[#if|<code>if()</code>]] function also follows the same rules to determine whether a value is true or false.

'''Note:''' Programmers familiar with other languages may occasionally be surprised by the fact that <code>and</code> and <code>or</code> do not short-circuit (which would mean that they will never evaluate their second argument if they can know their result solely from the first argument). This should not be a problem in general formula usage, since functions do not have side-effects, but it could make a difference when using the debug functions.

=== Operator Precedence ===

The precedence of various operators is, more or less, what you'd expect - you can write something like <syntaxhighlight lang='wfl' inline>a + b * 2 <= 5 and n - m / 4 > 7</syntaxhighlight> and the engine will do what you expect - first multiplication and division, then addition and subtraction, then comparison, and finally logical conjunction. The only thing to watch out for is when chaining exponentiation - all operators are left associative, so <syntaxhighlight lang='wfl' inline>a ^ b ^ c</syntaxhighlight> will be evaluated as <syntaxhighlight lang='wfl' inline>(a ^ b) ^ c</syntaxhighlight> instead of <syntaxhighlight lang='wfl' inline>a ^ (b ^ c)</syntaxhighlight> like you would expect. {{DevFeature1.13|5}} This has been fixed - exponentiation is now right-associative.

The full precedence list is as follows, from lowest to highest; operators on the same line have equal precedence.

# <code>not</code>
# <code>where</code> clauses
# <code>or</code>
# <code>and</code>
# Comparison operators <code>= != < <= > >= in</code>
# Range-generating operator <code>~</code>
# Additive operators <code>+ - ..</code>
# Multiplicative operators <code>* /</code>
# Modulus <code>%</code>
# Exponentiation <code>^</code>
# Dice operator <code>d</code>
# Dot operator <code>.</code>

== Functions ==

WFL is a ''functional'' language, so of course it has functions. There is a large library of [[#Core Functions|built-in functions]], and you can also [[#Defining Functions|define your own]].

Calling a function is simple, and works exactly how you would expect if you've worked with functions in a mathematical context: <syntaxhighlight lang=wfl inline>clamp(value, 0, 21)</syntaxhighlight>

Being a functional language, WFL does not have conditional or looping statements. Instead, these are provided by functions. For a simple conditional, you can use the <tt>if</tt> function, as in the following example:

<syntaxhighlight lang=wfl>
if(hitpoints > 37,
max_hitpoints / 2,
hitpoints - 3
)
</syntaxhighlight>

Similarly, looping is done via functions. There are several built-in higher-order functions that can be used to iterate over lists and maps, such as <tt>filter</tt>, <tt>choose</tt>, <tt>map</tt>, and <tt>reduce</tt>. See the corresponding function definitions for more information.

== Variables ==

Formulas may have a variety of variables, depending on the context in which they are evaluated. A string substitution formula like <code>$(3 + 5)</code> has no variables, but a [[StandardUnitFilter|unit filter]] formula has variables such as <code>hitpoints</code> and <code>max_hitpoints</code> which contain various properties of the unit being tested (the same unit which is also referred to in variable substitution as <code>$this_unit</code>). The special variable <code>self</code> typically refers to the "global context" - in the case of a unit filter formula, the unit itself. This means for example that <code>self.hitpoints</code> and <code>hitpoints</code> are equivalent when used in a unit filter formula. In a string substitution formula (the <code>$(formula)</code> syntax), <code>self</code> is null. Because of this, you should prefer not to use the substitution syntax in places where formulas are specifically supported.

A formula may declare additional variables using a <code>where</code> clause. This assigns a meaning to any unknown variables in the preceding formula. The general syntax is:

<formula> where <variable> = <value> [, <variable> = value ...]

This functions similarly to an operator, so if desired, you could have multiple where clauses in a single formula. Note that all variables in WFL are read-only - they are variables because they may have different values depending on the context in which the formula is evaluated, but for a given context, they are constant. A variable that has not been assigned a value is considered to have a value of null. Variables are lazily-evaluated - if a where clause declares a variable that is never used, the expression assigned to it will never be evaluated. (This only really matters if it contains a call to a debug function.)

Variable names can contain letters and underscores only. In particular, they cannot contain digits. Also, names are case-sensitive, so ''y'' and ''Y'' refer to two different variables. The following names are reserved and cannot be used for the name of a variable or function:

* <tt>d</tt> - dice operator
* <tt>or</tt> - logical operator
* <tt>in</tt> - containment operator
* <tt>def</tt> - defines a function
* <tt>and</tt> - logical operator
* <tt>not</tt> - logical operator
* <tt>fai</tt> - deprecated synonym of <tt>wfl</tt>
* <tt>wfl</tt> - declares filename
* <tt>where</tt> - declares variables
* <tt>faiend</tt> - deprecated synonym of <tt>wflend</tt>
* <tt>wflend</tt> - closes file scope
* <tt>functions</tt> - lists all defined functions

== Comments ==

Sometimes with particularly complicated formulas, it may be useful to document what's going on inline. Of course, you can use WML comments to do this, but in some cases it may be useful to put some comments in the middle of the formula. This is easily done - simply enclose them in <code>#</code> characters, like this:

<syntaxhighlight lang='wfl'>
#This is a Wesnoth Formula Language comment.#
</syntaxhighlight>

Note the final <code>#</code> - unlike WML, WFL requires this to indicate where the comment ends.

== Defining Functions ==

There are several predefined functions in the Wesnoth Formula Language, and if these are not enough, it is possible to define your own functions. The special variable <syntaxhighlight lang='wfl' inline>functions</syntaxhighlight> always evaluates to a list of all known function names. This is mainly useful only as a debugging tool, though.

To define a function, you use the <code>def</code> keyword. For example:

<syntaxhighlight lang='wfl'>
def sgn(x) if(x < 0, -1, x > 0, 1, 0);
</syntaxhighlight>

This defines a function called <code>sgn</code> which returns the sign of the input number. The semicolon marks the end of the function. It's optional if there's nothing else following the function, but in practice this will very rarely be the case.

Function names have the same limitation as variable names – they can contain only letters and underscores, and cannot contain digits.

You can select one of the function's arguments to be the "default" argument. If an object is passed to the default argument, then any attributes of that object are directly accessible in the global scope. For example:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u*) hitpoints < max_hitpoints / 2;
</syntaxhighlight>

This function takes a unit and returns 1 if it is at less than half hitpoints. The <code>*</code> indicates the default argument, without which it would instead have to be defined like this:

<syntaxhighlight lang='wfl'>
def is_badly_wounded(u) u.hitpoints < u.max_hitpoints / 2;
</syntaxhighlight>

It's important to remember that the function body has access to no variables other than its parameters. For example, the following function would not work (in a unit filter context) even though the unit variable is defined:

<syntaxhighlight lang='wfl'>
def endangers_me(u) distance_between(u.loc, unit.loc) < u.moves;
</syntaxhighlight>

This is because the body of the function can't see the unit variable. To make this work, you would need to pass in unit as an additional parameter.

'''Note: Prior to 1.14, function definitions only work in AI code and GUI2 code.'''

== Where to Use Formulas ==

Formulas can only be used in specific attributes in WML. The documentation of a WML tag will note which keys can have a formula placed in them. Some common examples include [[FilterWML|filters]], [[GUIToolkit|GUI2 dialogs]], and [[AbilitiesWML|unit abilities]]. Another example is the [[VariablesWML#Variable_Substitution|<code>$(formula)</code> substitution]] syntax, which allows the use of formulas wherever variables are parsed.

When using a formula in WML (other than in a substitution, which is usually part of a longer already-quoted passage), it is highly recommended to place double quotes around the formula, to avoid ambiguity between the WML and WFL parsers. The double angle quotes are also acceptable for this purpose. If you don't quote your formulas, there are two issues you could run into:

# WML uses the <code>+</code> operator to represent concatenation of strings, as well as line continuation. Because of this, an unquoted <code>+</code> will be ''removed'', likely causing the WFL formula to fail to compile.
# Unquoted WML text has the whitespace collapsed. If using WFL strings where whitespace is significant, this can result in surprises. For example, the formula <syntaxhighlight lang=wfl inline>length('One Two Three')</syntaxhighlight> would return 13 instead of the expected 19 if double quotes are not placed around the formula.

Some attributes in WML ''require'' a formula, which means that anything placed in the attribute will always be considered to be a formula. In this case, the formula doesn't need to be enclosed in parentheses – just the double quotes will suffice. However, there are also attributes that take an ''optional'' formula. These are most common in GUI2, but are also found in other places. In such attributes, the formula ''must'' be enclosed in parentheses. Failure to do so will result in it being parsed as just a straight value. As a general guideline, if the attribute key contains the word "formula", it is usually required to be a formula, whereas attributes with optional formulas do ''not'' contain the word "formula" in the key.

'''Note''': Do ''not'' use a <code>$</code> to introduce a formula. The <code>$</code> is not part of WFL syntax. It introduces a ''substitution'', a concept which is covered in more detail at [[VariablesWML#Variable Substitution]]. Although WFL can be used ''inside'' a substitution, a substitution itself is not WFL, and you should ''never'' use a <code>$</code> in WFL. However, in practice, substitutions and WFL are often used together – as substitution is processed first, you may see WFL formulas that appear to contain a <code>$</code> inside them. This is ''not'' part of the WFL – it is more like a macro substitution to be carried out before the formula runs. So, of course, it will only work in places that support ''both'' WFL and substitution.

== Files ==

{{DevFeature1.13|5}}

On occasion, you may find yourself working with formulas complex enough to split them out into a separate file. The formula engine normally assumes that it is executing inline code and reports errors accordingly, but you can tell it to enter a file scope using the special <code>wfl</code> keyword. The convention is to frame your code, so that any file looks like this:

<syntaxhighlight lang='wfl'>
wfl 'filename.wfl'

# Put whatever code you need here, possibly including function definitions. #

wflend
</syntaxhighlight>

The matching <code>wflend</code> is required.

'''Note:''' This functionality was available prior to 1.13.5 using keywords <code>fai</code> and <code>faiend</code>. {{DevFeature1.19|14}} As of 1.19.14, support for the <code>fai</code> and <code>faiend</code> keywords has been removed.

These directives have no effect on the formula code itself. They only change how error messages are reported if something goes wrong. Files using these directives are usually included using the WML preprocessor, though they could also be loaded in Lua with [[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]].

== Core Functions ==

Many of the core functions exhibit two features that (as of 1.13.4) cannot be used in user-defined functions. The first is the ability to accept a varying number of arguments - some core functions accept any number of arguments, while others have a few optional arguments. The second is that arguments are lazily-evaluated, and in some cases some arguments will not be evaluated at all, while others may be evaluated multiple times with different variable values. The description of each function will explain how and when its arguments are evaluated.

Most of the core functions can be used from any formula. However, there are some that are only available in formulas that have access to the game state. The following formulas have access to the game state and can use those functions:

* Formulas used in [[FilterWML]]
* Formulas used in [[AbilitiesWML]]
* <tt>filter_formula</tt> in [[EventWML#filter_formula|EventWML]]
* Formulas evaluated from the formula console (accessed by pressing F)

The following formulas do not have access to the game state and cannot use those functions:

* Formulas used in [[GUI2]]
* [[SyntaxWML#formula_substitution|Substitution]] formulas using <tt>$(...)</tt>
* [[ImagePathFunctions#CHAN: General function|IPF]] formulas used in <tt>~CHAN()</tt> or <tt>~ALPHA()</tt>
* Formulas compiled from [[LuaAPI/wesnoth#wesnoth.compile_formula|Lua]]

=== Conditional Functions ===

There are two functions which return one of their input values based on some condition - the <code>if</code> function, and the <code>switch</code> function. Both evaluate only as many parameters as is needed to determine which value to return. In particular, parameters that are neither returned nor part of the condition will never be evaluated.

==== if ====

* if(''condition'', ''if true'' [, ''condition 2'', ''if true 2'', ...] [, ''otherwise''])

This function first evaluates the ''condition'', which is a formula. If it evaluates to true, then the function evaluates and returns the ''if true'' parameter; otherwise, it tries the next condition (if any) with the same result. If none of the conditions evaluate to true, then it returns the ''otherwise'' parameter if present, or <code>null()</code> otherwise.

For instance, an event that is triggered by Wolf Riders on the first turn, and Orcish Grunts thereafter might have a unit filter formula that looks like this:

<syntaxhighlight lang='wfl'>
if(turn_number = 1, type = 'Wolf Rider', type = 'Orcish Grunt))
</syntaxhighlight>

==== switch ====

* switch(''formula'', ''value 1'', ''outcome 1'' [, ... , ''value N'', ''outcome N''] [, ''default outcome''])

The switch function first evaluates the input ''formula'', and then checks if it is equal to any of the specified ''values''. If matching value is found, the ''outcome'' assigned to it is returned; if not, then function returns either ''default outcome'' (if specified) or null.

=== Numeric Functions ===

Several basic math functions are available. These generally work equally on integer and decimal values.

==== abs ====

* abs(''number'')

Returns the absolute value of an input number; for example

<syntaxhighlight lang='wfl'>
abs( -5 )
</syntaxhighlight>

will return 5.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== acos ====

{{DevFeature1.13|5}}

* acos(''number'')

Returns the arccosine of the input number, in degrees.

==== asin ====

{{DevFeature1.13|5}}

* asin(''number'')

Returns the arcsine of the input number, in degrees.

==== atan ====

{{DevFeature1.13|5}}

* atan(''number'')

Returns the arctangent of the input number, in degrees.
==== as_decimal ====

* as_decimal(''number'')

Ensures that the number is a decimal rather than an integer; useful if you're dividing two unknown values and want to ensure that the result is a decimal.

==== cbrt ====

{{DevFeature1.13|5}}

* cbrt(''number'')

Returns the cube root of the input number. This is better than using the exponentiation operator, because it will give the correct result for negative numbers.

==== ceil ====

* ceil(''number'')

Returns the ceiling of the specified number, ie rounding it up to the nearest integer.

==== clamp ====

{{DevFeature1.17|0}}

* clamp(''number'', ''min'', ''max'')

Combines min and max into a single call. If ''number'' is less than ''min'', returns ''min''; if it's greater than ''max'', returns ''max''. Otherwise, returns ''number''.

==== cos ====

* cos(''angle'')

Returns the cosine of the given angle, which is specified in degrees.

==== exp ====

{{DevFeature1.13|5}}

* exp(''number'')

Returns the exponential of the input number, which is the constant ''e'' raised to the specified power.

==== floor ====

* floor(''number'')

Returns the floor of the specified number, ie rounding it down to the nearest integer.

==== frac ====

{{DevFeature1.13|5}}

* frac(''number'')

Returns the fractional part of the specified number.

==== hypot ====

{{DevFeature1.13|5}}

* hypot(''x'', ''y'')

Returns the hypoteneuse length of a triangle with sides ''x'' and ''y''.

==== lerp ====

{{DevFeature1.17|0}}

* lerp(''min'', ''max'', ''fraction'')

Returns a linear interpolation between ''min'' and ''max'' according to the specified ''fraction''.

==== lerp_index ====

{{DevFeature1.19|4}}

* lerp_index(''list'', ''ratio'')

Returns the element of the list that is closest to being at the specified ratio of the list's length.

'''Example''': <syntaxhighlight lang=wfl inline>lerp_index([1, 12, 32, 10], 0.26])</syntaxhighlight> returns 12.

==== log ====

{{DevFeature1.13|5}}

* log(''number'', [, ''base''])

Returns the logarithm of the input number. If ''base'' is omitted, it returns the natural logarithm; otherwise, the logarithm to the specified base.

==== max ====

* max(''list of numbers'')

Returns the largest number from the list. For example:

<syntaxhighlight lang='wfl'>
max([2, 8, -10, 3])
</syntaxhighlight>

will return <code>8</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== min ====

* min(''list of numbers'')

Returns the smallest number from the list. For example:

<syntaxhighlight lang='wfl'>
min( [ 3, 7, -2, 6] )
</syntaxhighlight>

will return <code>-2</code>.

{{DevFeature1.13|5}} This now works on decimals as well as integers.

==== pi ====

{{DevFeature1.13|5}}

* pi()

Returns pi.

==== root ====

{{DevFeature1.13|5}}

* root(''number'', ''base'')

Returns the root of the input number, to the specified base. This is better than using the exponentiation operator, because it will give the correct result for negative numbers and odd bases (for example, the fifth root of -32, which is -2).

==== round ====

* round(''number'')

Returns the specified number rounded to the nearest integer.

==== sgn ====

{{DevFeature1.13|5}}

* sgn(''number'')

Returns the sign of the number, ie -1 if it is negative, 1 if it is positive, and 0 if it is zero.

==== sin ====

* sin(''angle'')

Returns the sine of the given angle, which is specified in degrees.

==== sqrt ====

{{DevFeature1.13|5}}

* sqrt(''number'')

Returns the square root of the input number.

==== sum ====

* sum(''list of numbers'')

This function evaluates to the sum of the numbers in the ''list of numbers''. For example:

<syntaxhighlight lang='wfl'>
sum([ 2, 5, 8])
</syntaxhighlight>

returns <code>15</code>, and:

<syntaxhighlight lang='wfl'>
sum(map(my_units, max_hitpoints - hitpoints))
</syntaxhighlight>

finds the total damage your units have taken.

==== tan ====

{{DevFeature1.13|5}}

* tan(''number'')

Returns the tangent of the given angle, which is specified in degrees.

==== trunc ====

{{DevFeature1.13|5}}

* trunc(''number'')

Returns the truncation of the specified number, ie rounding it towards zero. This is different from floor when applied to negative numbers - floor(-7.5) gives -8, but trunc(-7.5) gives -7.

==== wave ====

* wave(''number'')

Given a numeric value V, this returns:

sin(2*pi*V)

=== String Functions ===

There are a few useful functions for manipulating strings.

==== concatenate ====

* concatenate(''value1''[, ''value2'', ...])

Converts each of its arguments to a string, and concatenates the result together into a single string.

==== contains_string ====

* contains_string(''string'', ''search_string'')

Returns 1 if ''search_string'' can be found within ''string'' (as a substring), 0 otherwise. For example:

<syntaxhighlight lang='wfl'>
contains_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>1</code>.

==== length ====

* length(''string'')

Returns the length of the input string.

==== ends_with ====

{{DevFeature1.19|4}}

* ends_with(''string'', ''suffix'')

Determines whether the ''string'' ends with the specified ''suffix''.

==== find_string ====

{{DevFeature1.13|5}}

* find_string(''string'', ''search_string'')

Returns the index at which ''search_string'' starts within ''string'' (as a substring), or -1 if it is not found. For example:

<syntaxhighlight lang='wfl'>
find_string( 'Testing', 'ing' )
</syntaxhighlight>

returns <code>4</code>.

==== replace ====

{{DevFeature1.13|5}}

* replace(''string'', ''offset'', [''size'',] ''replacement'')

Returns a new string obtained by replacing a portion of the input ''string'' with the contents of the ''replacement'' string. The ''offset'' and ''size'' work the same as for <code>substring</code>. Examples:

<syntaxhighlight lang='wfl'>
replace('The quick brown fox jumps over the lazy dog!', 4, 5, 'dumb')
replace('The quick brown fox jumps over the lazy dog!', -9, 4, 'sleeping')
replace('The quick brown fox jumps over the lazy dog!', -9, 'brook!')
replace('The quick brown fox jumps over the lazy dog!', -6, -4, 'yellow')
</syntaxhighlight>

return the following strings:

'The dumb brown fox jumps over the lazy dog!'
'The quick brown fox jumps over the sleeping dog!'
'The quick brown fox jumps over the brook!'
'The quick brown fox jumps over the yellow dog!'

==== replace_all ====

{{DevFeature1.19|4}}

* replace_all(''string'', ''match'', ''replacement'')

Returns a copy of ''string'' with all occurrences of ''match'' replaced by ''replacement''.

==== starts_with ====

{{DevFeature1.19|4}}

* starts_with(''string'', ''prefix'')

Determines whether the ''string'' begins with the specified ''prefix''.

==== substring ====

* substring(''string'', ''offset''[, ''size''])

Extracts a substring from the given input string. The ''offset'' specifies the first character to extract; the first character is <code>0</code>, and negative values count from the end, so the last character is <code>-1</code>. If specified, the ''size'' indicates the total number of characters to extract; it cannot be negative. If omitted, all characters from the ''offset'' to the end of the string are returned. For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', 4, 5)
substring('The quick brown fox jumps over the lazy dog!', -9, 4)
substring('The quick brown fox jumps over the lazy dog!', -9)
</syntaxhighlight>

return <code>'quick'</code>, <code>'lazy'</code>, and <code>'lazy dog!'</code> respectively.

{{DevFeature1.13|5}} The ''size'' can now be negative. This means to count backwards from the given ''offset'' (but always including the given offset, so a ''size'' of -1 gives the same result as 1). For example:

<syntaxhighlight lang='wfl'>
substring('The quick brown fox jumps over the lazy dog!', -6, -4)
</syntaxhighlight>

returns <code>'lazy'</code>.

=== List and Map Functions ===

This section contains functions that directly manipulate a map or list.

==== head ====

* head(''list'' [, ''count''])

Returns the first item from the ''list''; for example

<syntaxhighlight lang='wfl'>
head([5, 7, 9])
</syntaxhighlight>

returns <code>5</code>, and

<syntaxhighlight lang='wfl'>
head( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Orc'</code>.

{{DevFeature1.13|5}} If a second argument is given, it returns a list containing the first ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>head(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>head(L,1)</syntaxhighlight> - the former returns the first element, while the latter returns a list containing only the first element.

==== index_of ====

* index_of(''value'', ''list'')

This function will return the first index where ''value'' can be found in the input ''list''. It will return -1 if the value is not found in the ''list'.

==== keys ====

* keys(''map'')

Extracts the key values from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
keys(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

['Elvish Fighter', 'Elvish Archer']

==== size ====

* size(''list'')

This function returns the number of elements in the ''list''.

For example, <syntaxhighlight lang='wfl' inline>size([5, 7, 9])</syntaxhighlight> returns <code>3</code> and <syntaxhighlight lang='wfl' inline>size(['Archer', 'Fighter'])</syntaxhighlight> returns <code>2</code>.

==== sort ====

* sort(''list'', ''formula'')

This function evaluates to a result list sorted according to the comparison ''formula'' for each item <code>a</code> and its successor <code>b</code>. For instance, sorting units according to hitpoints would be done by:

<syntaxhighlight lang='wfl'>
sort(my_units, a.hitpoints > b.hitpoints)
</syntaxhighlight>

To sort them in the reverse order, simply use <code><</code> instead of <code>></code>.

==== tail ====

{{DevFeature1.13|5}}

* tail(''list'' [, ''count''])

Returns the last item from the ''list''; for example

<syntaxhighlight lang='wfl'>
tail([5, 7, 9])
</syntaxhighlight>

returns <code>9</code>, and

<syntaxhighlight lang='wfl'>
tail( [ 'Orc', 'Human' ] )
</syntaxhighlight>

returns <code>'Human'</code>.

If a second argument is given, it returns a list containing the last ''count'' elements from the ''list''. Note that <syntaxhighlight lang='wfl' inline>tail(L)</syntaxhighlight> is different from <syntaxhighlight lang='wfl' inline>tail(L,1)</syntaxhighlight> - the former returns the last element, while the latter returns a list containing only the last element.

==== tolist ====

* tolist(''map'')

This function takes a map and return a list of key-value pair objects. For example:

<syntaxhighlight lang='wfl'>
tolist(['Elf' -> 10, 'Dwarf' -> 20])
</syntaxhighlight>

will return:

[{key->'Elf',value->10}, {key->'Dwarf',value->20}]

==== tomap ====

* tomap(''list A'' [, ''list B''])

This function takes one or two ''lists'' as input and returns a map. If only one list is specified, then the function will evaluate this list, count how many similar elements are found within the list, and return a map with keys being these elements, and values being a number representing how many of them the list contains. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf', 'elf', 'elf', 'human', 'human'])
</syntaxhighlight>

will return:

['elf' -> 3, 'dwarf' -> 1, 'human' -> 2]

{{DevFeature1.13|5}} However, if all the elements are key-value pairs such as those created by ''pair'' or ''tolist'', then this function will invert the effect of ''tolist'' and return the original map which would have produced the input list as output when passed to ''tolist''. If only some elements are key-value pairs, those elements will be directly converted into key-value pairs in the resulting map, while other values will be treated as described above.

If two lists are specified, then the elements of the first one will be used as a keys, and the elements of the second one as a values, when creating an output map. Note that these input lists must be of the same length. For example:

<syntaxhighlight lang='wfl'>
tomap(['elf', 'dwarf' ], [10, 20])
</syntaxhighlight>

will result in:

['elf' -> 10, 'dwarf' -> 20]

==== values ====

* values(''map'')

Extracts the values assigned to keys from an input ''map'' and returns them as a list. For example:

<syntaxhighlight lang='wfl'>
values(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])
</syntaxhighlight>

returns

[50, 60]

=== List-processing Functions ===

This section covers functions that operate on maps or lists by applying one or more formulas in succession to each element. Most return another map or list, <code>reduce</code> instead combines all the elements into a single result.

==== choose ====

* choose(''input'', [''self_name'',] ''formula'')

This function evaluates ''formula'' for each item in the ''input'' (which can be a list or a map). It will return the first item to which ''formula'' gave the highest value. For example:

<syntaxhighlight lang='wfl'>
choose(my_units, level)
</syntaxhighlight>

gives back the unit with the highest level.

The implicit input when evaluating a mapping/filtering function's ''formula'' component will be that specific item under evaluation (in this example one of "my_units"), and it can be explicitly referenced as <code>self</code> when necessary. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

When evaluating a map, we can reference each key by <code>key</code> and each value by <code>value</code>. In this case, the <code>self</code> variable is this key-value pair. For example:

<syntaxhighlight lang='wfl'>
choose(['elf' -> 10, 'dwarf' -> 20 ], value)
</syntaxhighlight>

will return a key-value pair

{key->'dwarf', value->20}

The curly braces are used in output to indicate that this is an object, not a map. It is not valid WFL syntax.

==== filter ====

* filter(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map). It will evaluate to a list or map which only contains items that the ''formula'' was true for. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable.

<syntaxhighlight lang='wfl'>
filter(my_units, hitpoints < max_hitpoints)
</syntaxhighlight>

will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

==== find ====

* find(''input'', [''self_name'',] ''formula'')

This function will run <formula> on each item in the <input> (which can be a list or a map) and will return the first item for which <formula> was true. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. For example:

<syntaxhighlight lang='wfl'>
find(units, type = 'Elvish Archer' )
</syntaxhighlight>

will return the first unit of type 'Elvish Archer'.

==== map ====

* map(''input'', [''self_name'',] ''formula'')

This function will run the ''formula'' on each item in the ''input'' (which can be a list or a map), and evaluate to a new list or map or a map, which contains the same number of items as in ''input'', with the formulas run on each item. The optional <self_name> parameter can be used to give a different name to the <code>self</code> variable. When run on a map, the resulting map has the same keys as the input map, but with the values updated to the results of the ''formula''. For example:

<syntaxhighlight lang='wfl'>
map([10,20], self*self)
</syntaxhighlight>

and

<syntaxhighlight lang='wfl'>
map([10,20], 'value', value*value)
</syntaxhighlight>

will both result in [100, 400]. The formula:

<syntaxhighlight lang='wfl'>
map(my_units, hitpoints)
</syntaxhighlight>

will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

<syntaxhighlight lang='wfl'>
map(['elf' -> 10, 'dwarf' -> 20 ], value*2)
</syntaxhighlight>

The above will produce ['elf' -> 20, 'dwarf' -> 40]. Note that in case of a map data type, the <code>map</code> function can only modify the value.

<syntaxhighlight lang='wfl'>
map(tomap([3,5,8,8]), value+key*100)
</syntaxhighlight>

The above will produce <code>[3 -> 301, 5 -> 502, 8 -> 801]</code>. This can be used to take a list and make a map containing pairs <code>[element_from_that_list -> f(element_from_that_list,number_of_repetitions_of_that_element_in_that_list)]</code> where <code>f</code> is an arbitrary function.

==== reduce ====

* reduce(''list'', [''identity'', ] ''formula'')

This function will run the ''formula'' on the first and second members of the ''list'', then on the result and the third member and so on until the list is depleted. The final result is then returned. The two variables used in the ''formula'' are always 'a' and 'b'.

For example, <syntaxhighlight lang='wfl' inline>reduce([1,2,3,4], a+b)</syntaxhighlight> returns <code>10</code> and <syntaxhighlight lang='wfl' inline>reduce([9,4,8,2], 10*a+b)</syntaxhighlight> returns <code>9482</code>.

{{DevFeature1.13|5}} The new ''identity'' argument specifies the starting value (which is null or 0 by default). If ''list'' is empty, then ''identity'' is returned. Otherwise, the list will be considered as if ''identity'' were an extra first element. For example, to calculate the product of a list of numbers, you might do something like this:
<syntaxhighlight lang='wfl'>
reduce(your_list, 1, a * b)
</syntaxhighlight>

This will return 1 if the list is empty, as expected - the product of no numbers is 1. If the list is not empty, adding 1 to the list will have no effect, since it is the multiplicative identity.

==== take_while ====

{{DevFeature1.13|5}}

* take_while(''list'', ''formula'')

Evaluates the ''formula'' for each element of the ''list'' until it finds one for which it evaluates to false, then returns a list of all elements up to but not including that element. For example:

<syntaxhighlight lang='wfl'>
take_while([1,5,3,6,3,7,9,5,6,4,12,2,53,2,1], self < 10)
</syntaxhighlight>

returns the list <code>[1,5,3,6,3,7,9,5,6,4]</code>.

==== zip ====

{{DevFeature1.13|5}}

* zip(''list1'', ... , ''listN'')
* zip(''list of lists'')

Takes a list of lists and generates a new list of lists such that list ''n'' contains element ''n'' of each of the original lists, in order. If the lists are not all of the same length, it treats them as if they were padded on the end with null values so that they are all the length of the longest list.

<syntaxhighlight lang='wfl'>
zip([1,2,3],[4,5,6])
zip([1,4],[2,5],[3,6])
</syntaxhighlight>

return <code>[[1,4],[2,5],[3,6]]</code> and <code>[[1,2,3],[4,5,6]]</code>, respectively.

=== Location Functions ===

Functions for working with locations on a hex map.

==== adjacent_locs ====

{{DevFeature1.13|9}}

* adjacent_locs(''center'')

Returns a list of all locations adjacent to the specified location. When called from a formula with access to the game state, it automatically excludes locations that don't exist on the map. Otherwise, it operates as if on an infinite map. This means you should generally not expect the returned list to contain exactly 6 elements.

==== are_adjacent ====

{{DevFeature1.13|9}}

* are_adjacent(''loc1'', ''loc2'')

Check if two locations are adjacent. Returns 1 (true) or 0 (false).

==== direction_from ====

{{DevFeature1.13|9}}

* direction_from(''start'', ''direction'', [''distance''])

Returns the hex reached by travelling in the specified direction from a starting hex for a certain distance (default 1 hex).

==== distance_between ====

{{DevFeature1.13|5}}

* distance_between(''start'', ''end'')

Returns the distance between the locations ''start'' and ''end'', which must be location objects such as those created by <code>loc()</code>.

'''Note:''' This function was already available in FormulaAI prior to 1.13.5; however, from 1.13.5 onward it is available to all formulas.

==== loc ====

* loc(''x'', ''y'')

Creates and returns a location object with the specified coordinates. If assigned to a variable ''pos'' (eg with a <code>where</code> clause), the individual coordinates can be accessed as <code>pos.x</code> and <code>pos.y</code>.

==== locations_in_radius ====

{{DevFeature1.13|9}}

* locations_in_radius(''center'', ''radius'')

Returns a list of all locations within a given radius of the specified center hex.
Only locations on the map will be returned.

==== nearest_loc ====

{{DevFeature1.19|14}}

* nearest_loc(''origin'', ''locations'')

Returns the location in the given list closest to ''origin''. All arguments must be location objects such as those created by <code>loc()</code>.

'''Note:''' This function was already available in FormulaAI prior to 1.19.14; however, from 1.19.14 onward it is available to all formulas.

==== relative_dir ====

{{DevFeature1.13|9}}

* relative_dir(''loc1'', ''loc2'')

Returns the direction you need to travel to progress from one location to another. The returned location is one of the six possible directions on the Wesnoth hex map, or an empty string if both locations are the same.

==== rotate_loc_around ====

{{DevFeature1.13|9}} but returns wrong result until {{DevFeature1.19|2}}

* rotate_loc_around(''center'', ''loc'', ''angle'')

Rotates a location around a given center to produce a new location. The angle is an integer between -6 and 6, which can be understood as a multiple of 60 degrees.

=== Miscellaneous Functions ===

Some functions really don't fit into any category. They are all listed here.

==== null ====

* null([''arguments''])

Evaluates each of its arguments (if any) in order, then returns null. Since formulas generally do not have side-effects, there is usually little point in specifying any arguments, but it could be thought of as a way to "comment out" a section of the formula while ensuring it remains syntactically valid.

==== pair ====

{{DevFeature1.13|5}}

* pair(''key'', ''value'')

Creates a key-value pair object, the same as those created by the ''tolist'' function.

==== reverse ====

{{DevFeature1.13|5}}

* reverse(''string or list'')

Returns the input string or list backwards.

==== type ====

{{DevFeature1.13|5}}

* type(''anything'')

Returns the type of its input as a string. Possible results are:

* <code>'integer'</code>
* <code>'decimal'</code>
* <code>'string'</code>
* <code>'list'</code>
* <code>'map'</code>
* <code>'null'</code>
* <code>'object'</code>

==== get_palette ====

{{DevFeature1.19|4}}

* get_palette(''name'')

Returns a list of colours that make up the named palette. Palettes are defined by a '''[color_palette]''' tag, usually in the [[GameConfigWML#Color_Palettes|game config]]. The palettes defined in core Wesnoth are '''magenta''', '''flag_green''', and '''ellipse_red'''. In addition to defined palettes, several hard-coded palettes are available by name. They are '''red_green_scale''', '''red_green_scale_text''', '''blue_white_scale''', and '''blue_white_scale_text'''. These are also defined in the game config, but not with a '''[color_palette]''' tag.

=== Debugging Functions ===

There are also a few functions that can be useful for debugging formulas, for example by displaying intermediate results to the screen. Note that this breaks the general rule that functions do not have side-effects.

==== debug ====

* debug([''formula''])

Starts a GUI formula debugger when evaluating a formula. It takes a formula, evaluates it and returns the result unchanged. '''Note:''' this does not appear to work in 1.13.3.

{{DevFeature1.13|5}} The formula allows you to step through the formula one operation at a time, viewing the current stack and execution trace. As of 1.13.5, you need to enable [[CommandMode|debug mode]] to use the debugger; otherwise, it will simply be skipped.

==== debug_print ====

'''you need to enable formula log (--log-info='scripting/formula') to see the result of this call'''

* debug_print([''explanation'' ,] ''formula'' )

This function can be used for debugging a formula. It takes a ''formula'', writes its result to the console, and returns it unchanged. For example:

<syntaxhighlight lang='wfl'>
debug_print([1, 2, 3])
</syntaxhighlight>

will result in printing to the console

[1, 2, 3]

and returning the same.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_print'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_print('My array: ', [1, 2, 3])
</syntaxhighlight>

will write in the console:

My array: [1, 2, 3]

and return

[1, 2, 3]

==== debug_profile ====

* debug_profile(''formula'' [, ''explanation''])

Evaluates the formula 1000 times and prints (as with debug_print) a number indicating the average time required to evaluate the formula. Mainly intended for internal testing, but could occasionally be useful for people working with complicated formulas. The optional ''explanation'' argument is used in the same way as in debug_print.

==== debug_float ====

* debug_float(''location'', [''explanation'',] ''formula'' )

This function can be used for debugging a formula. It takes a formula, floats a label containing the result on the hex specified (in the same way damage is displayed) and returns it unchanged. Note that the ''location'' here is an object type; it can be created with the <code>[[#loc|loc()]]</code> function. For example:

<syntaxhighlight lang='wfl'>
debug_float(me.loc, me.id)
</syntaxhighlight>

will make a label containing the id of the unit ''me'' float over the unit.

Return value is also the unit id.

We can specify an optional parameter ''explanation'' that helps to distinguish between multiple ''debug_float'' calls in the same formula:

<syntaxhighlight lang='wfl'>
debug_float( me.loc, 'id: ', me.id )
</syntaxhighlight>

will float the following label

id: unit_id

and return the unit id.

==== dir ====

* dir(''object'')

This function return a list of all attributes in ''object''. For example:

<syntaxhighlight lang='wfl'>
dir(my_leader)
</syntaxhighlight>

will result in the following output:

[ 'x', 'y', 'loc', 'id', 'type', 'name', 'leader', 'undead', 'traits', 'attacks', 'abilities', 'hitpoints',
'max_hitpoints', 'experience', 'max_experience', 'level', 'total_movement', 'movement_left', 'attacks_left',
'side', 'states', 'cost', 'usage', 'vars']

This command is useful in the formula command line, to get information about the attributes of different types of data.

=== Game State Functions ===

These are functions that access the game state. Therefore, they are not available in all formulas, as described above.

==== base_tod_bonus ====

* base_tod_bonus([''loc'', [''turn'']])

Evaluates the base time-of-day bonus, excluding the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== chance_to_hit ====

* chance_to_hit(''unit'', ''location or terrain'')

Calculates the base chance for the unit to be hit if it moved to the given location or terrain. This is essentially the inverse of its defense. It is returned as an integer between 0 and 100.

==== defense_on ====

* defense_on(''unit'', ''location or terrain'')

Calculates the defense that the unit would have if it moved to the given location or terrain. It is returned as an integer between 0 and 100.

==== enemy_of ====

* enemy_of(''self'', ''other'')

Determines whether two units are enemies. Returns 1 (true) or 0 (false).

==== get_unit_type ====

* get_unit_type(''id'')

Returns an object describing the specified unit type, or null if no such unit type exists. A unit type object has many of the same keys as a unit, excluding those that are expected to change over time such as <tt>hitpoints</tt> or <tt>name</tt>.

==== jamming_cost ====

* jamming_cost(''unit or unit type'', ''location or terrain'')

Calculates the jamming cost for the unit to block vision on the given location terrain.

==== is_fogged ====

{{DevFeature1.19|14}}

* is_shrouded(''loc'', ''side_number''])

Returns whether the given location is currently fogged from the point of view of the given side.

==== is_shrouded ====

{{DevFeature1.19|14}}

* is_shrouded(''loc'', ''side_number''])

Returns whether the given location is currently shrouded from the point of view of the given side.

==== movement_cost ====

* movement_cost(''unit or unit type'', ''location or terrain'')

Calculates the movement cost for the unit to enter the given location or terrain.

==== resistance_on ====

* resistance_on(''unit'', ''location'', ''type'', [''attacker''])

Calculates the unit's resistance to the given damage type when standing on the specified location. If specified, the ''attacker'' parameter should be 1 to indicate that the unit is the attacker, or 0 to indicate that it is the defender, as this status can affect resistances. By default, it is assumed to be the defender.

This is returned not as the raw resistance set in WML, but the actual resistance that the player sees, so it ranges between -100 and 100.

==== tod_bonus ====

* tod_bonus([''loc'', [''turn'']])

Evaluates the final time-of-day bonus, accounting for the effect of illumination from abilities or terrain. If no turn is specified, the current turn is used. If no location is specified, the bonus is calculated for the global schedule without taking any time areas into account, but if a location is specified, it will account for any time areas that might affect that location.

==== unit_at ====

* unit_at(''location'')

Returns the unit on the given location, or null if there is no unit there.

==== unit_tod_modifier ====

{{DevFeature1.19|14}}

* unit_tod_modifier(''unit'', [''loc''])

Returns the current combat damage modifier for the given unit for the current time of day, taking into account any abilities whose effects it is currently under (illuminates, for example). If no location is specified, the unit's current location will be used.

'''Note:''' Prior to 1.19.4, this function was available as the FormulaAI function ''timeofday_modifier''.

==== vision_cost ====

* vision_cost(''unit or unit type'', ''location or terrain'')

Calculates the vision cost for the unit to see through the given location or terrain.

=== Action Functions ===

These are special functions that represent an action to be executed. They don't actually execute the action, merely describe it – the action will be executed only after the formula has been fully evaluated.

Action functions can currently only be used in GUI2, in the '''actions''' key. This key must always evaluate to either an action or a list of actions.

==== set_var ====

* set_var(''name'', ''value'')

Sets a variable in the current '''self''' context to the specified value.

The result of this function is an object that has '''name''' and '''value''' keys with the passed-in values.

* safe_call(''main'', ''backup'')

Tries to execute the ''main'' action first. If that fails, the ''backup'' action is executed instead.

The ''backup'' formula can access a special '''error''' object, which in turn contains two values:

* '''status''': A status code representing the type of error. Currently, the only possible status is 5001, which means the current context is immutable.
* '''object''': The action that failed to execute – in other words, the result of evaluating the ''main'' formula.

The result of this function is an object that has a '''main''' key that contains the result of evaluating the main formula.

Wesnoth Formula Language

2026-01-07T19:48:56Z

Celtic Minstrel: /* Maps */ Document empty map literal

InternalActionsWML

2025-11-26T19:37:36Z

Celtic Minstrel: /* [set_variables] */ Document how an explicit index changes the behaviour of replace and merge modes

{{WML Tags}}

Part of [[ActionWML]], Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.

== Variable Actions ==

These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

=== [set_variable] ===

The '''[set_variable]''' tag is used to create and manipulate [[VariablesWML|WML variables]]. The [https://www.wesnoth.org/macro-reference.html#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [https://www.wesnoth.org/macro-reference.html#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.

* '''name''': the name of the variable to manipulate

* '''value''': set the variable to the given value (can be numeric or string). Use literal for no substitution. (see [[VariablesWML]])

* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollar signs.

* '''to_variable''': set the variable to the value of the given variable, e.g. 'to_variable=temp' would be equivalent to 'value=$temp'.

* '''add''': add the given amount to the variable.

* '''sub''': subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. The result is a float.<br />To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.

* '''divide''': divide the variable by the given number. The result is a float. Wesnoth 1.9 and later no longer uses integer division. Use a second tag with round=floor if you relied on this.

* '''modulo''': returns the remainder of a division.

* '''abs''': Returns the absolute value of the variable.

* '''root''': Use '''root=square''' to calculate the square root. {{DevFeature1.15|0}} Also supports '''root=cube''' and arbitrary integer roots.

* '''power''': Raise the variable to some power.

* '''rand''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'rand=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'rand=3..5'.<br>You may combine these, e.g. 'rand=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. If a number or item is repeated, it is sampled more frequently as appropriate. See [[MultiplayerContent]] for more info on the MP case.<br>Using rand= will automatically result in the current action being non undoable. Ignoring possible [allow_undo].

* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).

* {{anchor|join|'''[join]'''}} joins an array of strings to create a textual list
** '''variable''': name of the array
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to connect the elements
** '''remove_empty''': whether to ignore empty elements

* '''ipart''': Assigns the integer part (the part to the left of the decimal point) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the decimal point) of the referenced variable.

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.
**'''round=trunc''': {{DevFeature1.15|0}} Rounds towards zero; this is the same operation as '''ipart''', but operating on the value already contained in the variable rather than the value assigned to the key.

* '''min''', '''max''': {{DevFeature1.15|9}} Specify a comma-separated list of numbers; either the smallest or largest number in the list will be assigned to the variable.

* '''reverse=yes''': {{DevFeature1.15|9}} Reverses the string value of the variable. For example, "delfador" becomes "rodafled".

* '''formula''': Calculate the new value of the variable from a [[Wesnoth_Formula_Language|WFL]] formula operating on the old value. This is similar to using the '''$(...)''' syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

=== [set_variables] ===

Manipulates a WML array or container

* '''name''': the name of the array or container to manipulate

* '''mode''': one of the following values:
** ''replace'': will clear the variable '''name''' and replace it with given data. This is the default value. If given an explicit index, such as name=my_array[1], only that single element of the array is replaced, and the new data is inserted into that slot, potentially pushing other elements up. If ''not'' given an explicit index, the entire array is replaced.
** ''append'': will append given data to the current array. An explicit index is ignored if given.
** ''merge'': will merge in the given data into '''name'''. Attributes in '''[value]''' will overwrite any existing already in '''name'''. Tags in '''[value]''' modify the corresponding tag of the original value of '''name''', so for example the first '''[attack]''' tag in '''[value]''' would modify the first '''[attack]''' tag of '''name''' rather than appending a new '''[attack]''' tag. If given an explicit index, all the '''[value]''' and '''[literal]''' tags will be merged together into a single tag (as if with mode=append), and this resulting container will then be merged into the container at the specified element. A few special syntaxes are supported:
*** ''__remove=yes'': When used in a subtag, causes the corresponding subtag in '''name''' to be deleted rather than merged. Deletion happens after any other subtags have been merged.
*** ''add_to_xxx'': Adds its integer value to the integer value of '''xxx''' in '''name''', and sets '''xxx''' in '''name''' to the result. {{DevFeature1.13|8}} Now adds as real numbers rather than integers.
*** ''concat_to_xxx'': {{DevFeature1.13|8}} Similar to '''add_to_xxx''', but does string concatenation instead of numerical addition.
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. Otherwise, it is inserted so as to become the element at the specified index, meaning that the element previously at that index and all later elements are pushed up by one. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

* '''to_variable''': set the array or container to the value of the given variable

* {{anchor|set_variables-value|'''[value]'''}}: the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

* {{anchor|set_variables-literal|'''[literal]'''}}: same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags

*{{anchor|set_variables-split|'''[split]'''}}: splits a textual list into an array which will then be set to data
** '''list''': textual list to split
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored; defaults to ''value'' if omitted.
** '''separator''': separator to separate the elements; if omitted, each character of the string will become an element in the result array.
** '''remove_empty''': whether to ignore empty elements; ignored if '''separator''' is omitted

{{DevFeature1.13|4}} You can now mix '''[value]''', '''[literal]''', and '''[split]''' in the same '''[set_variables]''' tag. They will be processed in order of appearance. Multiple instances of [split] are also supported now.

=== Capturing Game Data ===

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

==== [store_gold] ====

Stores a side's gold into a variable.

* '''[[StandardSideFilter]]''': The first matching side's gold will be stored in the variable "variable".
* '''variable''': (default='gold') the name of the variable to store the gold in

==== [store_locations] ====

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). The array will include any unreachable border hexes, if applicable.

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. By default, all locations on the map are stored.

* '''variable''': the name of the variable (array) into which to store the locations. Defaults to '''location'''.

* '''mode''': {{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and locations which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and locations which match the filter will be added to the array after the existing elements.

==== [store_reachable_locations] ====

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). See note below for ''vision''.
* '''moves''': possible values ''current'' (default), ''max''. For ''movement'' and ''attack'', specifies whether to use the current or maximum movement points when calculating the range. Ignored for ''vision''.
* '''viewing_side''': If left unset then fog and shroud are ignored, hidden ambushers are not ignored, and the real reach of the units is stored. If set to a non-zero number, then the area stored for each unit matching the SUF is based on the information visible to that unit's side; it doesn't matter which non-zero number is given. Ignored completely for ''vision''.
* '''variable''': the name of the variable (array) into which to store the locations.

In 1.14 and before, the ''vision'' range is calculated as max movement range ignoring ZoC + 1 hex.

{{DevFeature1.15|12}} ''vision'' uses the same calculations as the fog and shroud, and handles:
* units with vision costs different to movement costs
* units whose vision points aren't the same as their max movement points
* jamming by enemy units

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to ''append'', the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.
'''Result'''

Variable will contain following members:
* '''color''': Team color used for ellipses, sprites, and flags. Will be one of the id's found in data/core/team-colors.cfg or a custom color defined by [[GameConfigWML#Color_Palettes|[color_range]]].
* '''controller''': Indicates type of player that control this side. ''Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''null''': If players assigns "Empty" to "Player/Type" in game lobby
* '''fog''': Indicates whether this side is affected by fog of war.
* '''gold''': The amount of gold the side has.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''side_name''': Translated string representing the side's description.
* '''team_name''': String representing the team's description. Sides with the same team_name are allied.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''': {{DevFeature1.13|7}} When the side will be considered defeated. See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''faction''': {{DevFeature1.13|7}} id of the selected faction, string (multiplayer-only)
* '''faction_name''': {{DevFeature1.13|7}} Name of the selected faction, string (multiplayer-only)
* '''num_units''' {{DevFeature1.13|7}}: The number of units the side currently has on the map.
* '''num_villages''' {{DevFeature1.13|7}}: The number of villages the side currently controls.
* '''total_upkeep''' {{DevFeature1.13|7}}: The number of unit levels the side is currently supporting.
* '''expenses''' {{DevFeature1.13|7}}: The amount of gold the side is currently spending to support units.
* '''net_income''' {{DevFeature1.13|7}}: The income the side gains per turn after expenses.
* '''base_income''' {{DevFeature1.13|8}}: The income the side gains per turn (same as [side] income key)

* {{DevFeature1.13|7}} All other keys and tags of the side that are contained in [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] .__cfg

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

* [[StandardSideFilter]]: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
* '''variable''': (default='location'): the name of the variable to store the location in
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

==== [store_time_of_day] ====

Stores time of day information from the current scenario into a WML variable container.

* '''x, y''': Location to store the time for. [[DirectActionsWML#.5Btime_area.5D|Time areas]] matter; illumination does not. If this is omitted, the global (location-independent) time is stored.

* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].

* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

==== [store_turns] ====

Stores the turn limit (the maximum number of turns). If there is no limit, this stores ''-1''.

* '''variable''': (default='turns') the name of the variable in which to store the turn limit.

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample '''list of these tags and keys''' can be found at [[InternalActionsWMLUnitTags]].

If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file). One can also use the [[CommandMode|:inspect]] command or the [[InterfaceActionsWML#.5Binspect.5D|[inspect]]] tag to open a game-state inspector dialog, which can be used to view unit properties.

Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] to re-create the unit with the modified variables.

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] and [[ConditionalActionsWML#.5Bforeach.5D|[foreach]]].

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. The units will be stored in order of their internal ''underlying_id'' attribute, which is usually in creation order (but you normally should not depend on the order).

* '''variable''': the name of the variable into which to store the unit(s)

* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to ''append'', the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.

* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.

==== [store_unit_defense] ====

{{DevFeature1.13|9}}

{{DevFeature1.15|7}} Fixed, was broken in 1.15.3

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is. A footpad on castle has 70% defense, so this function stores the value 30.)

* StandardUnitFilter
* '''loc_x''', '''loc_y''': x and y of a valid map location. The terrain on this location will be used for the defense calculation.
* '''terrain''': The terrain code for which unit defense should be calculated. If '''terrain''' is specified, '''loc_x''' and '''loc_y''' are ignored.
* '''variable''': the name of the variable into which to store the defense. default: "terrain_defense"

==== [store_unit_defense_on] ====

{{DevFeature1.15|7}} Similar to [store_unit_defense], but stores the same number that would be shown in the UI. For example, a footpad on castle has 70% defense, so this stores the value 70.

Takes the same attributes as [store_unit_defense], and defaults to storing the value in "terrain_defense".

==== [store_unit_type] ====

Stores a unit type definition into a variable.

* '''type''': (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

* '''variable''': the name of the variable into which to store the unit type information (default "unit_type")

* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable. If mode is set to ''replace'', the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to ''append'', the variable will not be cleared, and the unit type will be added to the array after the existing elements.

==== [store_unit_type_ids] ====

* '''variable''': the name of the variable into which to store a comma-separated list of all unit type IDs including all from all loaded addons

==== [store_villages] ====

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.

Note: This differs from using [store_locations] only in that the hexes considered for match are restricted to those with villages (those whose terrain type has its 'gives_income' flag set to true), in the same way that use of either the 'owner_side' key or the '[filter_owner]' will. In fact, if either of these are present, [store_villages] and [store_locations] will behave identically.

* '''variable''': the name of the variable (array) into which to store the locations (default: "location")
* '''[[StandardLocationFilter]]''' tags and keys as arguments

==== [store_items] ====

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [[InterfaceActionsWML#.5Bitem.5D|[item]]] (depending on what was set during creating the item).

*'''variable''': name of the wml variable array to use (default "items")
*'''[[StandardLocationFilter]]''' keys as arguments: only items on locations matching this [[StandardLocationFilter]] will be stored
*'''item_name''': {{DevFeature1.15|0}} if given, only items created with a matching '''[item]name=''' will be stored. As of 1.15.0, this does not support comma-separated lists.

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

Gets the relative direction from one hex to another. This is an interface to the function wesnoth uses to decide how a unit will face while it is moving / attacking / defending.

* '''[source]''' x and y must describe a map location
* '''[destination]''' similar
* '''variable''' name of the variable to store string result in (one of 'n', 'nw', 'ne', 's', 'sw', 'se')
* '''mode''' optional. 0 is the default setting corresponding to default wesnoth implementation used in animations. 1 is an alternate "radially symmetric" mode. The default mode breaks ties in the direction of south, since this makes more units face the player directly on screen. The radially symmetric mode breaks ties in the direction of counter-clockwise, and might be more appropriate in some cases.

==== [find_path] ====

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path (including the starting hex).

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]]
*'''variable''': the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
*'''allow_multiple_turns''': default no, if yes also moves that require more than one turn will be calculated.
*'''check_visibility''': default no, if yes the path will not be computed if some hexes are not visible due to shroud.
*'''check_teleport''': default yes; if no, teleport won't be taken in account while computing path.
*'''check_zoc''': default yes; if no, unit ZOCs won't be considered while calculating the path.
*'''nearest_by''': {{DevFeature1.15|2}} possible values "movement_cost" (default), "steps", "hexes"; if the [destination] SLF matches multiple hexes, the one that would need the least movement points to reach may not be the one that's closest as measured by '''hexes''', or closest as measured by steps, from the starting point. This option chooses which measurement to prefer.

More detail about multiple destinations and the return structure is on [[FindPathExplanation]] (moved out of this page because it has an image in it).

This is the structure of the variable returned by [find_path]:
[path]
hexes = non-zero if a path was successfully found.
if the path is calculated to an impassable hex, or the move requires multiple turns
and allow_multiple_turns is no, its value will be 0.
from_x, from_y = location of the unit
to_x, to_y = destination
movement_cost = total movement cost required by unit to reach that hex
required_turns = total turns required by unit to reach that hex
[step]
x, y = location of the step
terrain = terrain of the step
movement_cost = movement cost required by unit to reach that hex
required_turns = turns required by unit to reach that hex
[/step]
[/path]

==== [unit_worth] ====
Takes only an inline [[StandardUnitFilter]] (only the first matching unit will be used for the calculation) and outputs the following variables:
*'''cost''': the current unit cost
*'''next_cost''': the cost of the most expensive advancement
*'''health''': the health of the unit in percentage
*'''experience''': current experience in percentage
*'''unit_worth''': how much the unit is worth

Mainly used for internal AI checks, but one could in theory just do anything with it.

[event]
name=moveto
[unit_worth]
x,y=$x1,$y1
[/unit_worth]
[message]
id=$unit.id
message=_"I cost $cost gold, with $health|% of my hitpoints and $experience|% on the way to cost $next_cost|.
I am estimated to be worth $unit_worth"
[/message]
[clear_variable]
name=cost,next_cost,health,experience,unit_worth
[/clear_variable]
[/event]

=== [clear_variable] ===

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro [https://www.wesnoth.org/macro-reference.html#CLEAR_VARIABLE CLEAR_VARIABLE] is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

* '''name''': the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
** If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, <code>{CLEAR_VARIABLE my_awesome_array[2]}</code> deletes <code>my_awesome_array[2]</code>, but then moves <code>my_awesome_array[3]</code> to <code>my_awesome_array[2]</code>, moves <code>my_awesome_array[4]</code> to <code>my_awesome_array[3]</code>, and so on until the end of the array.
** Note that <code>{CLEAR_VARIABLE my_awesome_array}</code> deletes the entire array, but <code>{CLEAR_VARIABLE my_awesome_array[0]}</code> deletes only the first container.

=== [sync_variable] ===

{{DevFeature1.13|0}}

Sets one or multiple variables to the same value as on all clients and also on replays, it uses the value from the currently active side.
* '''name''' the name of the variable to synchonize this can be a comma seperated list.

== Other Internal Actions ==

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

=== [fire_event] ===

Trigger a WML event (used often for [[EventWML#Custom_events|custom events]])

* '''name''': the name of event to trigger
** ''(Optional)'' {{DevFeature1.13|6}}

* '''id''': ''(Optional)'' the id of a single event to trigger {{DevFeature1.13|6}}

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.

* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.

* {{DevFeature1.17|6}} '''[data]''': Additional arbitrary data to pass to the event. In addition to passing custom data, this can be used to set the '''damage_inflicted''' in an attack event or the '''owner_side''' in a village capture event. Values can be used by Lua. {{DevFeature1.19|9}} Values can be accessed as $data.

=== [remove_event] ===
{{DevFeature1.13|0}} Removes the event with the specified id.

* '''id''': the id of the event to remove. May be a comma separated list.

'''Note''': Only events whose IDs are explicitly specified will be removed. For example, this will ''not'' automatically remove events nested within the events with those IDs.

=== [role] ===

Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.

* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

* '''reassign''': {{DevFeature1.13|6}} Can be either yes or no, defaults to yes. If set to '''no''' then first search for a unit that already has this role, and if found use that unit.

* '''search_recall_list''': {{DevFeature1.13|5}} whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. {{DevFeature1.13|6}} If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it. If '''reassign''' is '''no''', this setting also affects the search for a unit that already has the role.

* '''[else]''' {{DevFeature1.13|5}} ActionWML to execute if the game is unable to find a unit to assign the role to. For example, this could be used to create a new unit satisfying the role.

* {{anchor|auto_recall|'''[auto_recall]'''}}: {{DevFeature1.13|6}} If present, and the role is assigned to a unit on the recall list, then that unit is recalled. Supports all unique keys of [[DirectActionsWML#.5Brecall.5D|[recall]]], but no [[StandardUnitFilter]].

* [[StandardUnitFilter]], do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

=== [random_placement] ===
{{DevFeature1.13|2}}

Selects randomly a given number of locations from a given set of locations and exectutes the given code for each of those locations.

* '''[filter_location]''': a [[StandardLocationFilter]].
* '''[command]''': contains ActionWml that is executed for each of the locations.
* '''num_items''': the number of locations that should be selected. There are several ways of specifying this:
** An integer, giving the exact number of locations to use. (Variable substitution is supported too.)
** {{DevFeature1.15|0}} A percentage, meaning that fraction of the total available spaces.
** {{DevFeature1.15|0}} A [[Wesnoth_Formula_Language|WFL]] formula. It has access to one variable, ''size'', which is the total number of available spaces. In order to identify it as a WFL formula, the entire expression must be enclosed in parentheses. (Do not use a '''$''', as that will cause it to see ''size'' as zero.)
** A Lua expression. As with a WFL expression, it can access the ''size'' variable. {{DevFeature1.15|0}} This is now deprecated.
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
* '''min_distance''': The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
* '''allow_less''': If yes, the tag will not show an error in case there were less than num_items locations available.

=== Flow control actions ===

{{DevFeature1.13|2}}

There are three actions that alter the flow of execution. They are '''[break]''', '''[continue]''', and '''[return]'''. All of them take no arguments.

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.
<syntaxhighlight lang=wml>
[event]
name=moveto
[fire_event]
name=return_please
[/fire_event]
[message]
message="Made it back"
[/message]
[/event]
[event]
name=return_please
[return][/return]
[/event]
</syntaxhighlight>

=== [unsynced] ===

{{DevFeature1.13|2}}

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example
<syntaxhighlight lang=wml>
[event]
name=moveto
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code
<syntaxhighlight lang=wml>
[event]
name=moveto
[unsynced]
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[/unsynced]
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

== Examples ==

=== Using [set_variables] to Create Arrays of WML ===

<syntaxhighlight lang=wml>
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
</syntaxhighlight>

This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.

== See Also ==
* [[VariablesWML]]
* [[ActionWML]]
** [[ConditionalWML]]
** [[DirectActionsWML]]
** [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

EffectWML

2025-11-05T01:25:15Z

Celtic Minstrel: typo

{{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 their full definition was included in '''[abilities]'''. Example: ''abilities=heals_8,regenerates''.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

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

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

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

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

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

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

== Where to Use Effects ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2025-11-05T01:24:38Z

Celtic Minstrel: typo

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

AbilitiesWML

2025-10-26T23:30:26Z

Celtic Minstrel: /* Common keys and tags for abilities with a value */ Fix typo

{{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'.
* '''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]]

ImagePathFunctions

2025-10-05T19:06:27Z

Celtic Minstrel: /* PAD: Pad function */ That fake offset thing does not work on all images, so make that clear.

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

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

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

== Changing the colors ==

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

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

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

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

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

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

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

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

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

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

'''~GS( )'''

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

'''~L(lightmap)'''

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

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

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

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

'''~NEG( )'''

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''~SEPIA()'''

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

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

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

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

== Transformations ==

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

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

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

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

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

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

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

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

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

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

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

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

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

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

=== XBRZ function ===

{{DevFeature1.13|0}}

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

'''~XBRZ(n)'''

== Cut-paste-extend ==

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

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

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

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

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

'''~CROP_TRANSPARENCY()'''

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

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

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

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

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

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

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

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

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

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

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

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

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

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

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

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

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

'''~WIPE_ALPHA()'''

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

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

== Miscellaneous ==

=== BL: Blurring function ===

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

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

=== CHAN: General function ===

{{DevFeature1.13|7}}

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

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

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

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

=== DARKEN: Removed function ===

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

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

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

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

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

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

=== Pseudo IPFs ===

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

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

{{DevFeature1.13|8}}

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

'''~NO_TOD_SHIFT()'''

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

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

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

'''~RIGHT()'''

== Creating an image file from IPFs ==

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

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

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

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

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

AddonServers

2025-09-17T03:50:40Z

Celtic Minstrel: That's supposed to be an external link; also, show the actual URL for both links

To connect to the default Add-on server from inside Wesnoth, use Add-ons option from the title screen. Alternatively, all web servers can be viewed at this page: [https://addons.wesnoth.org addons.wesnoth.org]. The web page is for reference purposes, archival purposes, and for people who cannot use the game client for technical reasons or otherwise. You may have a look at the list of add-ons available from each one and optionally download their contents from here. The recommended way is to install via the in-game client as mentioned earlier.

Also, from the in-game client, it is possible to connect to another version's Add-on server by using the correct port address like this: <code>addons.wesnoth.org:15018</code>, where the last two digits of the port specified (<code>15018</code>) are the same as the last two digits of the Wesnoth version whose add-on server you wish to connect to. In this example, it will connect to [https://addons.wesnoth.org/1.18/ addons.wesnoth.org/1.18/]. Note that this is in general not recommended because Add-ons from another version may not be compatible or refuse to correctly work, and is intended for advanced users or for development purposes only. The port scheme may change at any point in the future and is not recommended to be used as a permanent link.

EffectWML

2025-09-07T01:27:51Z

Celtic Minstrel: typo

{{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]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted. Adding twice and removing once still means the ability is gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [experimental_filter_ability] instead.
** {{DevFeature1.17|17}} '''[experimental_filter_ability]''': [[StandardAbilityFilter]] to match the abilities to remove.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image base path to use. Defaults to '''misc/ellipse'''. Can be set to '''none''' to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

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

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

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

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

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

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

== Where to Use Effects ==

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

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

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

== See Also ==

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

[[Category: WML Reference]]

LuaAPI/wml

2025-08-31T18:02:02Z

Celtic Minstrel: /* wml.matches_filter */ Linkify

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

The <tt>wml</tt> module contains functions for working with WML tables. This module is available starting in 1.14.0.

A WML table is a specially-formatted Lua table representing WML tags and values. For more detail on the format of WML tables, see [[LuaWML#Encoding_WML_objects_into_Lua_tables|LuaWML]].

== Functions ==

=== wml.attribute_count ===

{{DevFeature1.15|3}}

* '''wml.attribute_count'''(''config'') → ''count''

Returns the number of attributes in the specified WML table.

=== wml.child_array ===

* '''wml.child_array'''(''config'', ''child_tag_name'') → ''array''

Like [[#wml.child_range]], but returns an array instead of an iterator. Useful if you need random access to the children.

=== wml.child_count ===

* '''wml.child_count'''(''config'', ''child_tag_name'') → ''count''

Returns the number of children in the config with the given tag name.

=== wml.child_range ===

* '''wml.child_range'''(''config'', ''child_tag_name'') → ''iterator'' ⇒ ''wml table''

Returns an iterator over all the sub-tags of a WML object with the given name.

<syntaxhighlight lang=lua>
local u = wesnoth.units.find_on_map{ id = "Delfador" }[1]
for att in wml.child_range(u.__cfg, "attack") do
wesnoth.message(tostring(att.description))
end
</syntaxhighlight>

=== wml.find_child ===

{{DevFeature1.15|3}}

* '''wml.find_child'''(''config'', [''tag_name''], ''filter'') → ''child or nil'', ''index''

Finds a child of the given config that matches the given filter, and returns the child or nil if not found. The index of the child is also returned. If a tag name is specified, the search is restricted to that tag.

=== wml.get_child ===

* '''wml.get_child'''(''config'', ''child_tag_name'', [''id'']) → ''child_table''

Returns the first sub-tag of a WML object with the given name.

<syntaxhighlight lang=lua>
local u = wesnoth.units.find_on_map{ id = "Delfador" }[1]
local costs = wml.get_child(u.__cfg, "movement_costs")
wesnoth.message(string.format("Delfador needs %d points to move through a forest.", costs.forest))
</syntaxhighlight>

If a third parameter is passed, only children having a ''id'' attribute equal to it are considered.

=== wml.get_nth_child ===

* '''wml.get_nth_child'''(''config'', ''child_tag_name'', ''n'') → ''child_table''

Returns the ''n''th sub-tag of a WML object with the given name.

=== wml.remove_child ===

* '''wml.remove_child'''(''config'', ''child_tag_name'')

Deletes the first child tag with the given name. This does not work on vconfig objects, however.

=== wml.remove_children ===

{{DevFeature1.17|0}}

* '''wml.remove_children'''(''config'', ''child_tag_name'', ...)

Deletes all child tags with the given names. This does not work on vconfig objects, however. You can pass as many tag names as you want as separate arguments.

=== wml.tag ===

* '''wml.tag'''.''tag_name''(''contents'') → ''tag_table''

Returns a table representing a tag within a WML table; can be used to create subtags with less brackets. It's common to use direct-table invocation for this, omitting the function parentheses.

<syntaxhighlight lang=lua>
wesnoth.wml_actions.event { name = "new turn", wml.tag.message { speaker = "narrator", message = "?" } }
</syntaxhighlight>

=== wml.clone ===

{{DevFeature1.15|0}}

* '''wml.clone'''(''wml_table'') → ''cloned_table''

Returns a clone (deep copy) of the passed WML table.

=== wml.equal ===

{{DevFeature1.15|3}}

* '''wml.equal'''(''config'', ''config'') → ''true or false''

Tests whether two WML objects are equal. Equal objects will produce an empty diff, and will be serialized to the same string.

=== wml.valid ===

{{DevFeature1.15|3}}

* '''wml.valid'''(''table'') → ''is_wml''

Tests whether the passed table represents a valid WML table. It will also return true if passed a vconfig.

=== wml.matches_filter ===

* '''wml.matches_filter'''(''WML table'', ''filter'')''' → ''boolean''

Test if a config matches a WML filter (as [[FilterWML#Filtering_on_WML_data|<tt>[filter_wml]</tt>]]).

=== wml.load ===

{{DevFeature1.15|0}}

* '''wml.load'''(''file'', [''defines'', [''schema'']]) → ''config''

Loads WML from a file and optionally validates it against a schema. The file and schema (if present) must both be a valid WML path, and the schema must point to a [[SchemaWML]] file. All built-in schema files can be found directly in the "schema" folder – for example, "schema/game_config.cfg" is the schema for an add-on's (and core's) _main.cfg.

The second parameter can either be a boolean specifying whether or not to preprocess the file (defaults to true), or an array of macros to be defined in the preprocessor (which of course implies the file will be preprocessed). The second form only allows specifying names to be defined. It does not allow setting a value or anything more complex.

=== wml.parse ===

{{DevFeature1.15|0}}

* '''wml.parse'''(''string'', [''schema'']) → ''config''

Parses a string containing WML code and optionally validates it against the provided schema. Unlike load, this function does ''not'' run the preprocessor, though <tt>#textdomain</tt> directives will still be recognized.

=== wml.merge ===

{{DevFeature1.15|3}}

* '''wml.merge'''(''base table'', ''merge data'', [''mode'']) → ''merged config''

Merges two WML tables recursively, using the specified mode. Possible modes are '''merge''', '''replace''', and '''append'''. The modes work the same as in [[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]. The mode only affects how child tags are merged; merging of attributes is always done the same way. The default mode is '''merge'''.

=== wml.diff ===

{{DevFeature1.15|3}}

* '''wml.diff'''(''left'', ''right'') → ''diff config''

Compares two WML tables and produces an output table in [[DiffWML]] detailing their differences.

=== wml.patch ===

{{DevFeature1.15|3}}

* '''wml.patch'''(''base'', ''diff'') → ''patched config''

Takes a WML table and a diff in [[DiffWML]] format and returns a new WML table modified according to the diff's instructions.

=== wml.interpolate ===

{{DevFeature1.15|3}}

* '''wml.interpolate'''('''template''', '''variables''') → ''interpolated config''

Interpolates variables into a WML table, including '''[insert_tag]'''. This is the same as what a vconfig does implicitly, but can use any valid WML table as a source of variables.

<syntaxhighlight lang=lua>
local variables = {
-- A scalar variable
number = 100,
-- An array variable with two entries
wml.tag.list{value = 42, rank = 3},
wml.tag.list{value = 21, rank = 1},
}
local subst = {
key = "$number",
wml.tag.insert_tag{
name = "entry",
variable = "list"
}
}
local result = wml.interpolate(subst, variables)
print(wml.tostring(result))
</syntaxhighlight>

The above code will output the following WML in the Lua console:

<syntaxhighlight lang=wml>
key=100
[entry]
rank=3
value=42
[/entry]
[entry]
rank=1
value=21
[/entry]
</syntaxhighlight>

=== wml.tostring ===

* '''wml.tostring'''(''wml_table'') → ''string''

Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string. {{DevFeature1.15|0}} The string output is syntactically valid WML that if parsed would produce the same config.

<syntaxhighlight lang=lua>
wml.variables["number"] = 100
local vconfig = wml.tovconfig({ key = "$number", another_key = true,
{"a_subtag", { a_key_in_the_subtag = "foo" }}
})
wesnoth.message(wml.tostring(vconfig))
wesnoth.message(wml.tostring(vconfig.__literal))
</syntaxhighlight>

=== wml.tovconfig ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.tovconfig'''(''config'') → ''vconfig''

Converts a WML table into a proxy object which performs variable substitution on the fly. The proxy object can for most intents and purposes be treated as a read-only table - the length operator works as expected, as does the ipairs function. The pairs function also works, but it is a little different than on a plain table - it will return only the attributes of the vconfig and not the tags. See [[LuaWML#Encoding_WML_objects_into_Lua_tables|LuaWML]] for more information about the structure of a vconfig (which is the same as the structure of a WML table). A vconfig has four special keys (''__literal'', ''__parsed'', ''__shallow_literal'', ''__shallow_parsed'') which correspond to the functions in this module by the same name, but in most cases it is better to use the functions.

<syntaxhighlight lang=lua>
wml.variables["varname"] = "to_be_deleted"

-- correct
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" }
-- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable { name = "$varname" }
-- correct: "$varname" is replaced by "to_be_deleted" at the right time
wesnoth.wml_actions.clear_variable(wml.tovconfig { name = "$varname" })
</syntaxhighlight>

=== wml.literal ===

* '''wml.literal'''(''config'') → ''wml_table''

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. If the argument is ''nil'', it returns an empty table. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

<syntaxhighlight lang=lua>
function wml_actions.display_literal_value(cfg)
cfg = wml.literal(cfg)
wesnoth.message(tostring(cfg.value))
end
</syntaxhighlight>

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

=== wml.parsed ===

* '''wml.parsed'''(''config'') → ''wml_table''

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].

=== wml.shallow_literal ===

* '''wml.shallow_literal'''(''config'') → ''wml_table''

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].

=== wml.shallow_parsed ===

* '''wml.shallow_parsed'''(''config'') → ''wml_table''

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].

=== wml.all_variables ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.all_variables''' → ''table''

Returns a copy of all the WML variables currently set in the form of a WML table.

<syntaxhighlight lang=lua>
for key, value in pairs(wml.all_variables) do
if type(value) == "table" then
print(key, value[1], value[2])
else
print(key, value)
end
end
</syntaxhighlight>

=== wml.variables ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables'''.''variable'' ↔ ''variable_contents''
* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables'''[''variable_path''] ↔ ''variable_contents''

This table grants read-write access to the WML variables by their fully-qualified name. Looking up a non-existent variable yields nil; otherwise, it returns a scalar for a WML attribute and a table for a WML object. The format of the table is described in [[LuaWML#Encoding WML objects into Lua tables]].

<syntaxhighlight lang=lua>
wesnoth.fire("store_unit", { variable="my_unit", { "filter", { id="hero" } } })
local heros_hp = wml.variables["my_unit[0].hitpoints"]
wesnoth.message(string.format("The 'hero' unit has %d hitpoints.", heros_hp))
</syntaxhighlight>

Note that, if the variable name happens to designate a sequence of WML objects, only the first one (index 0) is fetched. If all the WML objects with this name should have been returned, use [[#wml.array_access.get]] instead. If you need a specific one, include the index in the lookup key.

Assigning to a key in this table converts the Lua object to a WML variable if possible. For a table, a WML object is created; otherwise, an attribute is created. Note that you cannot assign a simple array as it will be mistaken for a WML table and give an error. Assigning nil clears the variable.

<syntaxhighlight lang=lua>
wml.variables["my_unit.hitpoints"] = heros_hp + 10
</syntaxhighlight>

=== wml.variables_proxy ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables_proxy'''.''variable'' ↔ ''proxy''
* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.variables_proxy'''[''variable_path''] ↔ ''proxy''

Similar to <tt>wml.variables</tt>, but if the variable is a container, then the fields of the returned table are then proxies to the WML objects with the same names; reading/writing to them will directly access the WML sub-variables. Note that this is still somewhat experimental and doesn't allow you to fully treat variables as if they were standard Lua tables.

=== wml.array_access.get ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_access.get'''(''var_name'', [''context'']) → ''array of variable_contents''

Fetches all the WML container variables with given name and returns a table containing them (starting at index 1). The context specifies where to get variables from. You can pass either a unit or a side as the context in order to get an array from the unit variables or side variables, respectively.

<syntaxhighlight lang=lua>
function get_recall_list(side)
wesnoth.fire("store_unit", { x = "recall", variable = "LUA_recall_list" })
local l = wml.array_access.get "LUA_recall_list"
wml.variables.LUA_recall_list = nil
return l
end
</syntaxhighlight>

=== wml.array_access.get_proxy ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_access.get_proxy'''(''var_name'') → ''array of proxies''

Creates proxies for all the WML container variables with given name and returns a table containing them (starting at index 1). This function is similar to [[#wml.array_access.get]], except that the proxies can be used for modifying WML containers. Note that changes to the returned array itself will not be reflected in the variable, however; only changes to the array elements.

=== wml.array_access.set ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_access.set'''(''varname'', ''array'', [''context''])

Creates WML container variables with given name from given table. The context specifies where to put the variables. You can pass either a unit or a side as the context in order to set an array in the unit variables or side variables, respectively.

<syntaxhighlight lang=lua>
wml.array_access.set("target", { {t=t1}, {t=t2}, {t=t3} })
-- target[0].t <- t1; target[1].t <- t2; target[2].t <- t3
</syntaxhighlight>

=== wml.array_variables ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_variables'''.''variable'' ↔ ''array of variable_contents''
* {{LuaGameOnly}}{{LuaMapOnly}} '''wml.array_variables'''[''variable_path''] ↔ ''array of variable_contents''

Like '''wml.variables''', except that it works on arrays as with '''wml.array_access.get''' and '''wml.array_access.set'''. This is a little more convenient when working with global WML variables rather than unit or side variables.

=== wml.eval_conditional ===

* {{LuaGameOnly}} '''wml.eval_conditional'''(''conditional_tags'') → ''boolean''

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

<syntaxhighlight lang=lua>
local result = wml.eval_conditional {
wml.tag.have_unit { id = "hero" },
wml.tag.variable { name = "counter", numerical_equals = "$old_counter" }
}
</syntaxhighlight>

Note: Prior to 1.15.13, this was available as '''wesnoth.eval_conditional'''.

=== wml.fire ===

* {{LuaGameOnly}} '''wml.fire'''(''tag'', ''parameters'')
* {{DevFeature1.17|17}} {{LuaGameOnly}} '''wml.fire'''.''tag''(''parameters'')

Fire a WML action tag. Note: WML variables are substituted into the parameters table.

Note: Prior to 1.15.13, this was available as '''wesnoth.fire'''. The second form was available through '''helper.set_wml_action_metatable'''.

=== wml.error ===

* {{LuaGameOnly}} '''wml.error'''(''message'')

Interrupts the current execution and displays a WML error message. This is intended for error messages in the implementaton of custom ActionWML or ConditionalWML tags. For errors in a Lua API, the built-in '''error''' function is a more suitable choice.

<syntaxhighlight lang=lua>
local names = cfg.name or wml.error("[clear_variable] missing required name= attribute.")
</syntaxhighlight>

[[Category: Lua Reference]]

FilterWML

2025-08-31T18:00:11Z

Celtic Minstrel: /* Filtering on WML data */ Render the substituted parts in italics instead of bold

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane' or customised type. {{DevFeature1.17|23}} [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location. Does not work in 1.16. {{DevFeature1.17|17}} Works again.
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
* '''[filter_special]''': {{DevFeature1.19|6}} Filter on a weapon special by using[[StandardAbilityFilter]]
** '''active''': if active=yes, true if the special is active at the current location. If active=no, true whether or not it's currently active, in this case, one special encoded in [attack] can be checked.
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''attacks_used''': {{DevFeature1.17|13}} filter on attack's attack cost
* '''min_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''max_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable. Keys supported after specific version: {{DevFeature1.17|13}} '''attacks_used'''. {{DevFeature1.19|4}} '''min_range''', '''max_range'''.

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering on WML data ==

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between '''<>''' needs to be replaced by the actual data to be filtered for. The following conventions are possible:

* ''<key>'''='''<value>'': Means that the key '''key''' must be present with the specified '''value'''.
* '''glob_on_'''''<key>'''''='''''<glob>'': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In a glob, the '''*''' character matches any sequence of characters, while the '''?''' character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_'''''<key>'''''=*''' in a '''[not]''' tag.
* '''['''''<some_tag>''''']''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.

== Tutorial ==
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[AnimationWML#Animation_Filtering|Animation filtering]]
* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]
* [[FilterWML/Examples - How to use Filter]]

[[Category: WML Reference]]

Android

2025-08-05T17:52:22Z

Celtic Minstrel: /* Turning off Developer Mode */ Minor wording change, and code tags are for code, not UI elements

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

== Playing controls ==
* Tap a unit to select 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.

== 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.)

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

SingleUnitWML

2025-07-24T01:08:31Z

Celtic Minstrel: Remove formula AI documentation (but leave a link to the legacy page for posterity)

{{WML Tags}}
The '''[unit]''' tag describes a single unit on the map or in memory, for example Konrad.
It is different from the '''[unit_type]''' in '''[units]''', which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated '''[unit_type]'''.

'''[unit]''' can be used inside '''[side]''' ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)

This contains keys and tags which describe the unit's [[#Unit Data|persistent data]], as well as certain [[#Unit State|state variables]] which will also persist with the unit but will change frequently as gameplay progresses. Finally, there are some keys to set certain [[#Creation Options|one-time options]] for how the unit will be initially created, which will ''not'' persist beyond initial creation.

== Unit Data ==
The following keys and tags describe the unit itself, and will persist with the unit (though some may change automatically when the unit advances):
* {{anchor|type|'''type'''}}: the ID of the unit's unit type. This key is mandatory. See [[UnitTypeWML]].

* {{anchor|language_name|'''language_name'''}}: the name of the unit's unit type. See [[UnitTypeWML]].

* '''variation''': the [variation] of the [unit_type] as which the unit will appear.

* '''parent_type''': overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable. Defaults to 1, except when the [unit] tag appears inside a [side], in which case the unit always belongs to that side, and this key is ignored.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified, a random one will be generated for the unit to ensure that each unit has a unique '''id''' attribute (as will happen when a unit is recruited normally). In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.) Note: While it IS technically possible to create multiple units with the same ID, doing so may produce unpredictable results in many cases. WML should therefore be structured in such a way that no two units in existence ever end up with the same ID.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male (unless [[#random_gender|'''random_gender''']] is set to "yes"), but if the unit has only a female variant it will be female.

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set). Although this is a translated string, see [[GettextForWesnothDevelopers#Proper_nouns_in_strings|proper nouns in strings]] before using it in a translatable string.

* <span id="unrenamable">'''unrenamable'''</span>: if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit= (only relevant for units with '''canrecruit=yes''').

* {{anchor|filter_recall|'''[filter_recall]'''}}: A leader can only recall those units which pass the SUF. (Meaningful only if canrecruit=yes.)
**'''[[StandardUnitFilter]]''' tags and keys

* '''level''': the unit's current level. Defaults to the level of the [unit_type] described by [[#type|'''type''']]. This is generally not set manually.

* '''upkeep''': the amount of upkeep the unit will require each turn.
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''free''': synonymous with "loyal".
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. 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.

* '''overlays''': a comma-separated list of images that are overlayed on the unit.
** {{DevFeature1.15|0}} This key is supported when creating a unit from WML, but will be empty when writing the unit back to WML; the overlays will instead be stored as [modifications].

* <span id="max_hitpoints">'''max_hitpoints'''</span>: The maximum hitpoints the unit has when at full health. Default is the max HP set for the [unit_type] described by [[#type|'''type''']].

* '''max_experience''': The experience the unit needs to advance. Default is the experience required for the [unit_type] described by [[#type|'''type''']].

* {{anchor|max_moves|'''max_moves'''}}: The maximum number of movement points the unit has. Default is the number of movement specified for the [unit_type] described by [[#type|'''type''']].

* '''vision''': The the number of vision points to calculate the unit's sight range. Default is the number of vision points specified for the [unit_type] described by [[#type|'''type''']].

* '''jamming''': {{DevFeature1.15|0}} The number of jamming points for the unit. Default is the number of jamming points specified for the [unit_type] described by [[#type|'''type''']].

* '''flying''': 'yes' if the unit's [[UnitsWML#.5Bmovetype.5D|movetype]] has flying=yes. For units that don't fly, the '''flying''' attribute is generally omitted rather than being recorded as 'no'. In SingleUnitWML, this attribute has been called '''flying''' since it was added in 1.11.2, it was never called 'flies'.

* {{anchor|max_attacks|'''max_attacks'''}}: The number of attacks the unit can have per turn. Default is the number of attacks specified for the [unit_type] described by [[#type|'''type''']].

* '''profile''': sets a portrait image for this unit. Default is the portrait image set for the [unit_type] described by [[#type|'''type''']]. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** 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''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''dismissable''': {{DevFeature1.19|9}} If 'no', unit cannot be dismissed from the recall list using the ''Dismiss'' button in Unit Recall dialog. Default: 'yes'.

* '''block_dismiss_message''': {{DevFeature1.19|9}} Sets the message to be shown when ''dismissable'' is ''no'' and the user presses the ''Dismiss'' button in Unit Recall dialog. If not set, a default message will be shown instead.

* {{anchor|variables|'''[variables]'''}}: a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]). The subnode '''mods''' is special as it is deleted on every unit rebuild (for example when the unit advances or when an [object] is removed). This makes it possible to implement [effect]s that change variables, as those will also be reapplied whenever the unit is reset. (so in particular if your effect changes the variables mods.<whatever> [remove_object] will work properly for those objects.) For example the following code will define a apply_to=moves_on_recruits effect that gives units with that effect full movement when recruited

<syntaxhighlight lang='lua'>
function wesnoth.effects.move_on_recruit(u, cfg)
-- maybe better use a status than a variable ?
u.variables["mods.move_on_recruit"] = true
end
on_event("recruit,recall", function(ec)
local unit = wesnoth.get_unit(ec.x1, ec.y1)
if unit and unit.variables["mods.move_on_recruit"] then
unit.attacks_left = 1
unit.moves = unit.max_moves
end
end)
</syntaxhighlight>
And since we used the mods subtable, [remove_object] will work properly for objects that give this effect.

* {{anchor|modifications|'''[modifications]'''}}: a collection of tags describing changes that have been made to the unit. Any number and combination of tags of each type may be specified.
** '''[trait]''': a trait the unit has. Same format as [[UnitsWML#.5Btrait.5D|[trait], UnitsWML]].
** '''[object]''': an object the unit has. Same format as [[DirectActionsWML#.5Bobject.5D|[object], DirectActionsWML]].
** '''[advancement]''': an advancement (AMLA) that has been applied to the unit. Same format as [[UnitTypeWML#After max level advancement (AMLA)|[advancement], UnitTypeWML]]. These are automatically added when the player confirms an AMLA in the Advance Unit dialog, but they can also be specified manually to indicate that the unit already has a particular advancement applied; by providing only an advancement ID with no effects, it is even possible to disable a future advancement. {{DevFeature1.13|2}} In versions prior to 1.13.2, this tag was named [advance].

* '''[event]''' The event is copied from this unit's WML description into the scenario. The event is carried along with the unit (even during advancement) and inserted into a scenario whenever this unit is first included. A [unit][event] requires a non-empty id= attribute.

* '''description''': overrides the unit type description for this unit. Note that this will be reset when the unit advances. To avoid this, one can either set up a ''post_advance'' [[EventWML|event]] to override the default description after promotion, or use an [object] with a profile [[EffectWML|effect]] to change the unit description.

* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes]].

* '''ai_special''': causes the unit to act differently
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''[status] guardian = 'yes''''.

* {{anchor|ai|'''[ai]'''}}: This affects how the computer will control this unit.
** {{DevFeature1.15|?}} '''[candidate_action]''': Add a candidate action that only applies to this unit; see [[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|here]] for details. The [filter_own] tag is not supported.
*** '''stage''': If specified, the candidate action is added to the stage with the given ID, instead of the default stage (which is main_loop).
** {{DevFeature1.15|?}} '''[micro_ai]''': Add a micro AI that only applies to this unit; see [[Micro AIs]] for details. This tag does not support side, action, or [filter].
** Removed in {{DevFeature1.19|14}}: the '''[vars]''' tag and the '''formula''', '''loop_formula''', and '''priority''' keys were part of the legacy [[FormulaAI]] system.

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

*'''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is the alignment of the [unit_type] described by [[#type|'''type''']]. This is generally not set manually.

*'''advances_to''': comma-separated list of unit types to which this unit can advance. Will override the default provided by the [unit_type]. This is generally not set manually.

*'''race''': See {{tag|UnitsWML|race}}. Will override the default provided by the [unit_type]. This is generally not set manually.

*'''undead_variation''': Will override the default provided by the [unit_type]. This is generally not set manually.

*'''usage''': Will override the default provided by the [unit_type]. This is generally not set manually.

*'''zoc''': whether the unit has a zone of control. Will override the default provided by the [unit_type]. This is generally not set manually.

*'''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''': Can be used to modify [[UnitsWML#.5Bmovetype.5D|existing values]].

*'''[attack]''': Takes the same syntax as [[UnitTypeWML#Attacks|[unit_type][attack]]]. By default, the attacks from the [unit_type] will be included. '''Note:''' using this tag will replace ''all'' [attack] tags with the new one.

*'''hidden''': Implementation detail of [[InterfaceActionsWML#%5Bhide_unit%5D|[hide_unit]]]. This should not be set manually.

== Unit State ==
The following keys and tags describe the current state of the unit, and will change regularly as gameplay progresses:
* '''x''', '''y''': the location of the unit. By default (unless modified by [[#placement|'''placement''']] below) if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list. The recall list can also be explicitly specified as the location with "recall,recall".

* '''location_id''': {{DevFeature1.13|8}} the location of the unit, referencing one of the special locations defined by the map. This overrides '''x''' and '''y''' if present but otherwise has the same effect and can be modified by the placement options.

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Note that some unit types may not have distinct animations for each direction.

* '''goto_x''':, '''goto_y''': the unit's current movement destination. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default [[#max_hitpoints|'''max_hitpoints''']].

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is [[#max_moves|'''max_moves''']].
: '''Note:''' Do not assume that moves=max_moves on turns when the unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give the unit rest healing. Note that this can be true even if moves is not equal to max_moves.

* '''attacks_left''': number of attacks the unit has left. Default is '''max_attacks'''.

* {{anchor|status|'''[status]'''}}: the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, '''slowed''' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn. For cutscenes, it may be useful to set this manually.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed through normal game mechanics. This includes the healing by resting. It does ''not'' prevent the unit from being healed by WML or Lua code.
** '''unpoisonable''': if set to 'yes', the unit cannot be poisoned.
** '''undrainable''': if set to 'yes', the attacker can't gain health with drain ability attacking this unit.
** '''unplagueable''': if set to 'yes', the unit cannot be affected by plague attack.
** '''not_living''': Deprecated, this is automatically set when all three above are set and vice versa.
** '''unslowable''': if set to 'yes', the unit cannot be slowed.
** '''unpetrifiable''': if set to 'yes', the unit cannot be petrified.
** '''invulnerable''': {{DevFeature1.13|6}} if 'yes', attacks can't hit the unit. The AI and the attack dialog take it into account.
** One can add other keys to [status], but they must have boolean values, and they will not do anything meaningful on their own (but can be checked from events and acted upon accordingly). For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''invulnerable''': {{DevFeature1.13|6}} a shorthand to set the ''invulnerable'' status. Useful in [[CommandMode]] for debugging purposes. It's recommended to use [status] in written code instead.

== Creation Options ==
In addition to the unit's persistent data itself, there are several options for controlling how the unit will be created, as follows:
* <span id="placement">'''placement'''</span>: How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y (or location_id) are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y (or location_id) are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events. {{DevFeature1.13|8}} Deprecated, use placement=map and overwrite=yes instead.
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex. {{DevFeature1.13|8}} Deprecated, use placement=map and passable=yes instead.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed. {{DevFeature1.13|8}} Deprecated, use placement=leader and passable=yes instead.
* '''passable''': {{DevFeature1.13|8}} (default=no) If yes, and the specified location is of an impassable terrain for the unit being placed, the new unit will be placed in the nearest hex that is of a passable terrain for it.
* '''overwrite''': {{DevFeature1.13|8}} (default=no) If yes, always place the unit at the exact specified location, overwriting the existing unit if there is one. Generally you don't want to use this together with placement=leader.

* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.
* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give the unit fewer traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* <span id="random_gender">'''random_gender'''</span>: "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''to_variable''': (only for [event][unit]) creates the unit into the given variable instead of placing it on the map.

* '''animate''': whether to display the recruitment animation for this unit as if it were being recruited/recalled. Defaults to "no". Irrelevant when the [unit] tag appears inside a [side].

== See Also ==

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

[[Category:WML Reference]]

InternalActionsWML

2025-07-22T12:12:12Z

Celtic Minstrel: /* [remove_event] */ Try to clarify that nested events aren't permanently linked to their parent.

{{WML Tags}}

Part of [[ActionWML]], Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.

== Variable Actions ==

These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

=== [set_variable] ===

The '''[set_variable]''' tag is used to create and manipulate [[VariablesWML|WML variables]]. The [https://www.wesnoth.org/macro-reference.html#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [https://www.wesnoth.org/macro-reference.html#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.

* '''name''': the name of the variable to manipulate

* '''value''': set the variable to the given value (can be numeric or string). Use literal for no substitution. (see [[VariablesWML]])

* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollar signs.

* '''to_variable''': set the variable to the value of the given variable, e.g. 'to_variable=temp' would be equivalent to 'value=$temp'.

* '''add''': add the given amount to the variable.

* '''sub''': subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. The result is a float.<br />To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.

* '''divide''': divide the variable by the given number. The result is a float. Wesnoth 1.9 and later no longer uses integer division. Use a second tag with round=floor if you relied on this.

* '''modulo''': returns the remainder of a division.

* '''abs''': Returns the absolute value of the variable.

* '''root''': Use '''root=square''' to calculate the square root. {{DevFeature1.15|0}} Also supports '''root=cube''' and arbitrary integer roots.

* '''power''': Raise the variable to some power.

* '''rand''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'rand=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'rand=3..5'.<br>You may combine these, e.g. 'rand=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. If a number or item is repeated, it is sampled more frequently as appropriate. See [[MultiplayerContent]] for more info on the MP case.<br>Using rand= will automatically result in the current action being non undoable. Ignoring possible [allow_undo].

* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).

* {{anchor|join|'''[join]'''}} joins an array of strings to create a textual list
** '''variable''': name of the array
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to connect the elements
** '''remove_empty''': whether to ignore empty elements

* '''ipart''': Assigns the integer part (the part to the left of the decimal point) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the decimal point) of the referenced variable.

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.
**'''round=trunc''': {{DevFeature1.15|0}} Rounds towards zero; this is the same operation as '''ipart''', but operating on the value already contained in the variable rather than the value assigned to the key.

* '''min''', '''max''': {{DevFeature1.15|9}} Specify a comma-separated list of numbers; either the smallest or largest number in the list will be assigned to the variable.

* '''reverse=yes''': {{DevFeature1.15|9}} Reverses the string value of the variable. For example, "delfador" becomes "rodafled".

* '''formula''': Calculate the new value of the variable from a [[Wesnoth_Formula_Language|WFL]] formula operating on the old value. This is similar to using the '''$(...)''' syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

=== [set_variables] ===

Manipulates a WML array or container

* '''name''': the name of the array or container to manipulate

* '''mode''': one of the following values:
** ''replace'': will clear the array '''name''' and replace it with given data. This is the default value.
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''. Attributes in '''[value]''' will overwrite any existing already in '''name'''. Tags in '''[value]''' modify the corresponding tag of the original value of '''name''', so for example the first '''[attack]''' tag in '''[value]''' would modify the first '''[attack]''' tag of '''name''' rather than appending a new '''[attack]''' tag. A few special syntaxes are supported:
*** ''__remove=yes'': When used in a subtag, causes the corresponding subtag in '''name''' to be deleted rather than merged. Deletion happens after any other subtags have been merged.
*** ''add_to_xxx'': Adds its integer value to the integer value of '''xxx''' in '''name''', and sets '''xxx''' in '''name''' to the result. {{DevFeature1.13|8}} Now adds as real numbers rather than integers.
*** ''concat_to_xxx'': {{DevFeature1.13|8}} Similar to '''add_to_xxx''', but does string concatenation instead of numerical addition.
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

* '''to_variable''': set the array or container to the value of the given variable

* {{anchor|set_variables-value|'''[value]'''}}: the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

* {{anchor|set_variables-literal|'''[literal]'''}}: same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags

*{{anchor|set_variables-split|'''[split]'''}}: splits a textual list into an array which will then be set to data
** '''list''': textual list to split
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored; defaults to ''value'' if omitted.
** '''separator''': separator to separate the elements; if omitted, each character of the string will become an element in the result array.
** '''remove_empty''': whether to ignore empty elements; ignored if '''separator''' is omitted

{{DevFeature1.13|4}} You can now mix '''[value]''', '''[literal]''', and '''[split]''' in the same '''[set_variables]''' tag. They will be processed in order of appearance. Multiple instances of [split] are also supported now.

=== Capturing Game Data ===

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

==== [store_gold] ====

Stores a side's gold into a variable.

* '''[[StandardSideFilter]]''': The first matching side's gold will be stored in the variable "variable".
* '''variable''': (default='gold') the name of the variable to store the gold in

==== [store_locations] ====

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). The array will include any unreachable border hexes, if applicable.

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. By default, all locations on the map are stored.

* '''variable''': the name of the variable (array) into which to store the locations. Defaults to '''location'''.

* '''mode''': {{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and locations which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and locations which match the filter will be added to the array after the existing elements.

==== [store_reachable_locations] ====

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). See note below for ''vision''.
* '''moves''': possible values ''current'' (default), ''max''. For ''movement'' and ''attack'', specifies whether to use the current or maximum movement points when calculating the range. Ignored for ''vision''.
* '''viewing_side''': If left unset then fog and shroud are ignored, hidden ambushers are not ignored, and the real reach of the units is stored. If set to a non-zero number, then the area stored for each unit matching the SUF is based on the information visible to that unit's side; it doesn't matter which non-zero number is given. Ignored completely for ''vision''.
* '''variable''': the name of the variable (array) into which to store the locations.

In 1.14 and before, the ''vision'' range is calculated as max movement range ignoring ZoC + 1 hex.

{{DevFeature1.15|12}} ''vision'' uses the same calculations as the fog and shroud, and handles:
* units with vision costs different to movement costs
* units whose vision points aren't the same as their max movement points
* jamming by enemy units

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to ''append'', the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.
'''Result'''

Variable will contain following members:
* '''color''': Team color used for ellipses, sprites, and flags. Will be one of the id's found in data/core/team-colors.cfg or a custom color defined by [[GameConfigWML#Color_Palettes|[color_range]]].
* '''controller''': Indicates type of player that control this side. ''Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''null''': If players assigns "Empty" to "Player/Type" in game lobby
* '''fog''': Indicates whether this side is affected by fog of war.
* '''gold''': The amount of gold the side has.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''side_name''': Translated string representing the side's description.
* '''team_name''': String representing the team's description. Sides with the same team_name are allied.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''': {{DevFeature1.13|7}} When the side will be considered defeated. See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''faction''': {{DevFeature1.13|7}} id of the selected faction, string (multiplayer-only)
* '''faction_name''': {{DevFeature1.13|7}} Name of the selected faction, string (multiplayer-only)
* '''num_units''' {{DevFeature1.13|7}}: The number of units the side currently has on the map.
* '''num_villages''' {{DevFeature1.13|7}}: The number of villages the side currently controls.
* '''total_upkeep''' {{DevFeature1.13|7}}: The number of unit levels the side is currently supporting.
* '''expenses''' {{DevFeature1.13|7}}: The amount of gold the side is currently spending to support units.
* '''net_income''' {{DevFeature1.13|7}}: The income the side gains per turn after expenses.
* '''base_income''' {{DevFeature1.13|8}}: The income the side gains per turn (same as [side] income key)

* {{DevFeature1.13|7}} All other keys and tags of the side that are contained in [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] .__cfg

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

* [[StandardSideFilter]]: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
* '''variable''': (default='location'): the name of the variable to store the location in
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

==== [store_time_of_day] ====

Stores time of day information from the current scenario into a WML variable container.

* '''x, y''': Location to store the time for. [[DirectActionsWML#.5Btime_area.5D|Time areas]] matter; illumination does not. If this is omitted, the global (location-independent) time is stored.

* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].

* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

==== [store_turns] ====

Stores the turn limit (the maximum number of turns). If there is no limit, this stores ''-1''.

* '''variable''': (default='turns') the name of the variable in which to store the turn limit.

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample '''list of these tags and keys''' can be found at [[InternalActionsWMLUnitTags]].

If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file). One can also use the [[CommandMode|:inspect]] command or the [[InterfaceActionsWML#.5Binspect.5D|[inspect]]] tag to open a game-state inspector dialog, which can be used to view unit properties.

Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] to re-create the unit with the modified variables.

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] and [[ConditionalActionsWML#.5Bforeach.5D|[foreach]]].

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. The units will be stored in order of their internal ''underlying_id'' attribute, which is usually in creation order (but you normally should not depend on the order).

* '''variable''': the name of the variable into which to store the unit(s)

* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to ''append'', the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.

* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.

==== [store_unit_defense] ====

{{DevFeature1.13|9}}

{{DevFeature1.15|7}} Fixed, was broken in 1.15.3

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is. A footpad on castle has 70% defense, so this function stores the value 30.)

* StandardUnitFilter
* '''loc_x''', '''loc_y''': x and y of a valid map location. The terrain on this location will be used for the defense calculation.
* '''terrain''': The terrain code for which unit defense should be calculated. If '''terrain''' is specified, '''loc_x''' and '''loc_y''' are ignored.
* '''variable''': the name of the variable into which to store the defense. default: "terrain_defense"

==== [store_unit_defense_on] ====

{{DevFeature1.15|7}} Similar to [store_unit_defense], but stores the same number that would be shown in the UI. For example, a footpad on castle has 70% defense, so this stores the value 70.

Takes the same attributes as [store_unit_defense], and defaults to storing the value in "terrain_defense".

==== [store_unit_type] ====

Stores a unit type definition into a variable.

* '''type''': (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

* '''variable''': the name of the variable into which to store the unit type information (default "unit_type")

* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable. If mode is set to ''replace'', the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to ''append'', the variable will not be cleared, and the unit type will be added to the array after the existing elements.

==== [store_unit_type_ids] ====

* '''variable''': the name of the variable into which to store a comma-separated list of all unit type IDs including all from all loaded addons

==== [store_villages] ====

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.

Note: This differs from using [store_locations] only in that the hexes considered for match are restricted to those with villages (those whose terrain type has its 'gives_income' flag set to true), in the same way that use of either the 'owner_side' key or the '[filter_owner]' will. In fact, if either of these are present, [store_villages] and [store_locations] will behave identically.

* '''variable''': the name of the variable (array) into which to store the locations (default: "location")
* '''[[StandardLocationFilter]]''' tags and keys as arguments

==== [store_items] ====

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [[InterfaceActionsWML#.5Bitem.5D|[item]]] (depending on what was set during creating the item).

*'''variable''': name of the wml variable array to use (default "items")
*'''[[StandardLocationFilter]]''' keys as arguments: only items on locations matching this [[StandardLocationFilter]] will be stored
*'''item_name''': {{DevFeature1.15|0}} if given, only items created with a matching '''[item]name=''' will be stored. As of 1.15.0, this does not support comma-separated lists.

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

Gets the relative direction from one hex to another. This is an interface to the function wesnoth uses to decide how a unit will face while it is moving / attacking / defending.

* '''[source]''' x and y must describe a map location
* '''[destination]''' similar
* '''variable''' name of the variable to store string result in (one of 'n', 'nw', 'ne', 's', 'sw', 'se')
* '''mode''' optional. 0 is the default setting corresponding to default wesnoth implementation used in animations. 1 is an alternate "radially symmetric" mode. The default mode breaks ties in the direction of south, since this makes more units face the player directly on screen. The radially symmetric mode breaks ties in the direction of counter-clockwise, and might be more appropriate in some cases.

==== [find_path] ====

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path (including the starting hex).

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]]
*'''variable''': the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
*'''allow_multiple_turns''': default no, if yes also moves that require more than one turn will be calculated.
*'''check_visibility''': default no, if yes the path will not be computed if some hexes are not visible due to shroud.
*'''check_teleport''': default yes; if no, teleport won't be taken in account while computing path.
*'''check_zoc''': default yes; if no, unit ZOCs won't be considered while calculating the path.
*'''nearest_by''': {{DevFeature1.15|2}} possible values "movement_cost" (default), "steps", "hexes"; if the [destination] SLF matches multiple hexes, the one that would need the least movement points to reach may not be the one that's closest as measured by '''hexes''', or closest as measured by steps, from the starting point. This option chooses which measurement to prefer.

More detail about multiple destinations and the return structure is on [[FindPathExplanation]] (moved out of this page because it has an image in it).

This is the structure of the variable returned by [find_path]:
[path]
hexes = non-zero if a path was successfully found.
if the path is calculated to an impassable hex, or the move requires multiple turns
and allow_multiple_turns is no, its value will be 0.
from_x, from_y = location of the unit
to_x, to_y = destination
movement_cost = total movement cost required by unit to reach that hex
required_turns = total turns required by unit to reach that hex
[step]
x, y = location of the step
terrain = terrain of the step
movement_cost = movement cost required by unit to reach that hex
required_turns = turns required by unit to reach that hex
[/step]
[/path]

==== [unit_worth] ====
Takes only an inline [[StandardUnitFilter]] (only the first matching unit will be used for the calculation) and outputs the following variables:
*'''cost''': the current unit cost
*'''next_cost''': the cost of the most expensive advancement
*'''health''': the health of the unit in percentage
*'''experience''': current experience in percentage
*'''unit_worth''': how much the unit is worth

Mainly used for internal AI checks, but one could in theory just do anything with it.

[event]
name=moveto
[unit_worth]
x,y=$x1,$y1
[/unit_worth]
[message]
id=$unit.id
message=_"I cost $cost gold, with $health|% of my hitpoints and $experience|% on the way to cost $next_cost|.
I am estimated to be worth $unit_worth"
[/message]
[clear_variable]
name=cost,next_cost,health,experience,unit_worth
[/clear_variable]
[/event]

=== [clear_variable] ===

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro [https://www.wesnoth.org/macro-reference.html#CLEAR_VARIABLE CLEAR_VARIABLE] is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

* '''name''': the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
** If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, <code>{CLEAR_VARIABLE my_awesome_array[2]}</code> deletes <code>my_awesome_array[2]</code>, but then moves <code>my_awesome_array[3]</code> to <code>my_awesome_array[2]</code>, moves <code>my_awesome_array[4]</code> to <code>my_awesome_array[3]</code>, and so on until the end of the array.
** Note that <code>{CLEAR_VARIABLE my_awesome_array}</code> deletes the entire array, but <code>{CLEAR_VARIABLE my_awesome_array[0]}</code> deletes only the first container.

=== [sync_variable] ===

{{DevFeature1.13|0}}

Sets one or multiple variables to the same value as on all clients and also on replays, it uses the value from the currently active side.
* '''name''' the name of the variable to synchonize this can be a comma seperated list.

== Other Internal Actions ==

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

=== [fire_event] ===

Trigger a WML event (used often for [[EventWML#Custom_events|custom events]])

* '''name''': the name of event to trigger
** ''(Optional)'' {{DevFeature1.13|6}}

* '''id''': ''(Optional)'' the id of a single event to trigger {{DevFeature1.13|6}}

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.

* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.

* {{DevFeature1.17|6}} '''[data]''': Additional arbitrary data to pass to the event. In addition to passing custom data, this can be used to set the '''damage_inflicted''' in an attack event or the '''owner_side''' in a village capture event. Values can be used by Lua. {{DevFeature1.19|9}} Values can be accessed as $data.

=== [remove_event] ===
{{DevFeature1.13|0}} Removes the event with the specified id.

* '''id''': the id of the event to remove. May be a comma separated list.

'''Note''': Only events whose IDs are explicitly specified will be removed. For example, this will ''not'' automatically remove events nested within the events with those IDs.

=== [role] ===

Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.

* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

* '''reassign''': {{DevFeature1.13|6}} Can be either yes or no, defaults to yes. If set to '''no''' then first search for a unit that already has this role, and if found use that unit.

* '''search_recall_list''': {{DevFeature1.13|5}} whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. {{DevFeature1.13|6}} If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it. If '''reassign''' is '''no''', this setting also affects the search for a unit that already has the role.

* '''[else]''' {{DevFeature1.13|5}} ActionWML to execute if the game is unable to find a unit to assign the role to. For example, this could be used to create a new unit satisfying the role.

* {{anchor|auto_recall|'''[auto_recall]'''}}: {{DevFeature1.13|6}} If present, and the role is assigned to a unit on the recall list, then that unit is recalled. Supports all unique keys of [[DirectActionsWML#.5Brecall.5D|[recall]]], but no [[StandardUnitFilter]].

* [[StandardUnitFilter]], do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

=== [random_placement] ===
{{DevFeature1.13|2}}

Selects randomly a given number of locations from a given set of locations and exectutes the given code for each of those locations.

* '''[filter_location]''': a [[StandardLocationFilter]].
* '''[command]''': contains ActionWml that is executed for each of the locations.
* '''num_items''': the number of locations that should be selected. There are several ways of specifying this:
** An integer, giving the exact number of locations to use. (Variable substitution is supported too.)
** {{DevFeature1.15|0}} A percentage, meaning that fraction of the total available spaces.
** {{DevFeature1.15|0}} A [[Wesnoth_Formula_Language|WFL]] formula. It has access to one variable, ''size'', which is the total number of available spaces. In order to identify it as a WFL formula, the entire expression must be enclosed in parentheses. (Do not use a '''$''', as that will cause it to see ''size'' as zero.)
** A Lua expression. As with a WFL expression, it can access the ''size'' variable. {{DevFeature1.15|0}} This is now deprecated.
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
* '''min_distance''': The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
* '''allow_less''': If yes, the tag will not show an error in case there were less than num_items locations available.

=== Flow control actions ===

{{DevFeature1.13|2}}

There are three actions that alter the flow of execution. They are '''[break]''', '''[continue]''', and '''[return]'''. All of them take no arguments.

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.
<syntaxhighlight lang=wml>
[event]
name=moveto
[fire_event]
name=return_please
[/fire_event]
[message]
message="Made it back"
[/message]
[/event]
[event]
name=return_please
[return][/return]
[/event]
</syntaxhighlight>

=== [unsynced] ===

{{DevFeature1.13|2}}

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example
<syntaxhighlight lang=wml>
[event]
name=moveto
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code
<syntaxhighlight lang=wml>
[event]
name=moveto
[unsynced]
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[/unsynced]
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

== Examples ==

=== Using [set_variables] to Create Arrays of WML ===

<syntaxhighlight lang=wml>
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
</syntaxhighlight>

This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.

== See Also ==
* [[VariablesWML]]
* [[ActionWML]]
** [[ConditionalWML]]
** [[DirectActionsWML]]
** [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]