The Battle for Wesnoth Wiki - User contributions [en]

InternalActionsWML

2011-12-19T19:02:02Z

Exasperation: /* [store_unit] */ changed description of mode attribute to match changed behavior

{{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 WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#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 dollars signs.

* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value. {{DevFeature1.9}}The format attribute is no longer available; use value instead.

* '''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. To subtract, add a negative number.

* '''sub''' {{DevFeature}}: subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. Floating point values are not rounded.

* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used. {{DevFeature1.9}}Integer division is no longer used. Use floor function in addition if you relied on this.

* '''modulo''': returns the remainder of a division.

* '''random''': no longer supported in {{DevFeature1.9}}; use rand= instead

* '''rand''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. See [[BuildingMultiplayerExamples]] for more info on the MP case.

* '''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).

* '''[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 comma) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the comma) 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:
**'''ceil''': Rounds upward to the nearest integer.
**'''floor''': Rounds down to the nearest integer.

=== [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 clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''
** ''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''': data will be set to the given array

* '''[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]])

* '''[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

*'''[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
** '''separator''': separator to separate the elements
** '''remove_empty''': whether to ignore empty elements

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

* '''side''': (default=1) the side for which the gold should be stored
* '''[[StandardSideFilter]]''' {{DevFeature1.9}} (instead of just side= above) 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. You must specify this or no locations will be stored.

* '''variable''': the name of the variable (array) into which to store the locations.

==== [store_reachable_locations] {{DevFeature1.9}} ====

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). If ''vision'', stores the vision range (movement range ignoring Zone of Control + 1 hex).
* '''moves''': possible values ''current'' (default), ''max''. Specifies whether to use the current or maximum movement points when calculating the range.
* '''viewing_side''': (optional) the side whose vision to use when calculating the reach. This only has meaning in the presence of fog, shroud, or units with the ambush ability. If left out, then fog, shroud and ambushers are ignored and the real reach of the units is stored.
* '''variable''': the name of the variable (array) into which to store the locations.

==== [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. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour' (becomes 'color' in 1.9+), 'controller', 'village_gold', 'recruit', and {{DevFeature1.9}} 'side' (the $side_number of the side belonging to this container).

* '''side''': the side whose information should be stored
* '''[[StandardSideFilter]]''': {{DevFeature1.9}} instead of only side=. 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")

''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''

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

* '''side''': the side whose starting location is to be stored
* [[StandardSideFilter]] tags and keys {{DevFeature1.9}}
* '''variable''': (default='location'): the name of the variable to store the location in

==== [store_time_of_day] ====

Stores time of day information from the current scenario into a WML variable container.

* '''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_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 [[InternalActionsWMLUnitTags|here]]. 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).

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 [http://www.wesnoth.org/macro-reference.xhtml#FOREACH 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_type] ====

* '''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")

==== [store_unit_type_ids] ====

* '''variable''': the name of the variable into which to store a comma-separated list of all unit type IDs

==== [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'. Although only owner_side and terrain filters are explained below, all features of the [[StandardLocationFilter]] are fully supported.

* '''variable''': the name of the variable (array) into which to store the locations

* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.

* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.

==== [store_items] ====
{{DevFeature1.9}}

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

==== [find_path] ====
{{DevFeature1.9}}

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.

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]], only the first matching nearest hex will be used
*'''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.
This is the structure of the variable returned by [find_path]:
[path]
length = the total length of the path
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]

=== [clear_variable] ===

This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.

* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.

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

* '''name''': the name of event to trigger

* '''[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.

=== [insert_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. ([[#.5Binsert_tag.5D_Example|See Example]]).

Tag insertion is a special case in that it can be used in places where other ActionWML cannot be used. The basic rule is that anywhere that $variable syntax works, tag insertion will also work. In practice this means pretty much everywhere except directly within top-level scenario tags.

*'''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''': Name of the container variable which will have its value inserted into the tag.

=== [role] ===

Tries to find a unit to assign a role to. 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]]). 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.

== Examples ==

=== Using [set_variables] to Create Arrays of 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}

This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.

=== [insert_tag] Example ===

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

This is effectively identical to:

[event]
name=moveto

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

== See Also ==
* [[VariablesWML]]
* [[ActionWML]]
** [[ConditionalWML]]
** [[DirectActionsWML]]
** [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

LuaWML

2011-12-09T20:21:13Z

Exasperation: /* User interface */

{{WML Tags}}

== The '''[lua]''' tag ==

This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.1] language.

The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.

[lua]
code = << wesnoth.message "Hello World!" >>
[/lua]

The Lua kernel can also be accessed from the [[CommandMode|command mode]]:

:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5

The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".

[lua]
code = << local t = ...; wesnoth.message(tostring(t.text)) >>
[args]
text = _ "Hello world!"
[/args]
[/lua]

== Global environment ==

All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.

[event]
name = preload
first_time_only = no
[lua]
code = <<
function narrator(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
>>
[/lua]
[/event]

[event]
name = turn 1
[lua]
code = << narrator(...) >>
[args]
sentence = _ "Hello world!"
[/args]
[/lua]
[lua]
code = << narrator(...) >>
[args]
sentence = _ "How are you today?"
[/args]
[/lua]
[/event]

In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.

[event]
name = preload
first_time_only = no
[lua]
code = <<
-- The function is now local, since its name does not have to be
-- visible outside this Lua scripts.
local function handler(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
-- Create a new tag named [narrator].
wesnoth.register_wml_action("narrator", handler)
>>
[/lua]
[/event]

[event]
name = turn 1
[narrator]
sentence = _ "Hello world!"
[/narrator]
[narrator]
sentence = _ "How are you today?"
[/narrator]
[/event]

The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.

The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. In {{DevFeature1.9}} the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library (Keep in mind that they aren't multiplayer- and replay-save.) and traceback from the [http://www.lua.org/manual/5.1/manual.html#5.9 debug] library are also available.

At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.

== Examples ==

The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.

# General catch for them moving to the wrong place.
[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[if]
[variable]
name=target_hex.is_set
equals=yes
[/variable]
[then]
[if]
[variable]
name=x1
equals=$target_hex.x
[/variable]
[variable]
name=y1
equals=$target_hex.y
[/variable]
[then]
[/then]
[else]
[redraw][/redraw]
[message]
speaker=narrator
message=_ "*Oops!
You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +
_ "
*Left click or press spacebar to continue..."
[/message]
[/else]
[/if]
[/then]
[/if]
[/event]

A Lua script that performs the same action is presented below.

[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[lua]
code = <<
local event_data = wesnoth.current.event_context
if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)
then
W.redraw()
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")
end
>>
[/lua]
[/event]

Here is a more detailed explanation of the Lua code. Its first line

local event_data = wesnoth.current.event_context

puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.

The next two lines then test

if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)

whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
-- skipping some other initializations
-- ...
H.set_wml_var_metatable(_G)
>>
[/lua]
[/event]

Without a prelude redirecting ''_G'', the conditional would have been written

if wesnoth.get_variable("target_hex.is_set") and
(event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")

The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.

W.redraw()

Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.

W = H.set_wml_action_metatable {}

Without this shortcut, the first statement would have been written

wesnoth.fire("redraw")

Finally the script displays a message by

narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")

The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is

function narrator_says(m)
W.message { speaker="narrator",
message = m .. _ "\n*Left click or press spacebar to continue..." }
end

The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:

_ = wesnoth.textdomain "wesnoth-tutorial"

A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].

== Interface to the engine and helper functions ==

Functionalities of the game engine are available through the functions of the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.

Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].

helper = wesnoth.require "lua/helper.lua"

=== WML variables ===

* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]
* [[LuaWML:Variables#helper.get_child|helper.get_child]]
* [[LuaWML:Variables#helper.child_range|helper.child_range]]
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]

=== Events and WML actions ===

* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]
* [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]] {{DevFeature1.9}}
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]] {{DevFeature1.9}}
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]] {{DevFeature1.9}}
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]
* [[LuaWML:Events#helper.literal|helper.literal]] {{DevFeature1.9}}
* [[LuaWML:Events#helper.parsed|helper.parsed]] {{DevFeature1.9}}
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]] {{DevFeature1.9}}
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]] {{DevFeature1.9}}

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.highlight_hex|wesnoth.highlight_hex]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]
* [[LuaWML:Display#wesnoth.get_time_of_day|wesnoth.get_time_of_day]] {{DevFeature1.9}}

=== Map and terrains ===

* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]] {{DevFeature1.9}}
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]] {{DevFeature1.9}}
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]] {{DevFeature1.9}}
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]] {{DevFeature1.9}}
* [[LuaWML:Tiles#items.place_image|items.place_image]] {{DevFeature1.9}}
* [[LuaWML:Tiles#items.place_halo|items.place_halo]] {{DevFeature1.9}}
* [[LuaWML:Tiles#items.remove|items.remove]] {{DevFeature1.9}}

=== Units ===

* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]
* [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.races|wesnoth.races]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]] {{DevFeature1.9}}
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]] {{DevFeature1.9}}

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] {{DevFeature1.9}}
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]] {{DevFeature1.9}}
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]] {{DevFeature1.9}}
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]] {{DevFeature1.9}}
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]] {{DevFeature1.9}}
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]

=== Pathfinder ===

* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]] {{DevFeature1.9}}

=== Lua files ===

* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]

=== Location sets ===

* [[LuaWML:Location_set#location_set.create|location_set.create]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:empty|location_set:empty]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:size|location_set:size]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:clear|location_set:clear]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:get|location_set:get]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:insert|location_set:insert]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:remove|location_set:remove]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:union|location_set:union]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:inter|location_set:inter]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:iter|location_set:iter]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:filter|location_set:filter]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]] {{DevFeature1.9}}
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]] {{DevFeature1.9}}

=== Miscellaneous ===

* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]] {{DevFeature1.9}}
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]] {{DevFeature1.9}}
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]] {{DevFeature1.9}}
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]] {{DevFeature1.9}}
* [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]
* [[LuaWML:Misc#helper.rand|helper.rand]] {{DevFeature1.9}}

== Encoding WML objects into Lua tables ==

Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.

Scalar fields are transformed into WML attributes. For instance, the following Lua table

{
a_bool = true,
an_int = 42,
a_float = 1.25,
a_string = "scout",
a_translation = _ "Hello World!"
}

is equivalent to the content of the following WML object

[dummy]
a_bool = "yes"
an_int = "42"
a_float = "1.25"
a_string = "scout"
a_translation = _ "Hello World!"
[/dummy]

WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form {[1] = "tag_name", [2] = {}} which is equivalent to {"tag_name", {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { z = 5, { "barfoo", {} } } }
}

is equivalent to the content of the following WML object

[dummy]
foo = 42
[bar]
v = 1
w = 2
[/bar]
[foo]
x = no
[/foo]
[bar]
y = foo
[bar]
[foobar]
z = 5
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:
{
foo = 42,
[1] = { [1] = "bar", [2] = { v = 1, w = 2 } },
[2] = { [1] = "foo", [2] = { x = false } },
[3] = { [1] = "bar", [2] = { y = "foo" } },
[4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }
}

So assuming ''cfg'' contains the above WML object, the following accesses are possible:

a_int = cfg.foo -- "dummy.foo", 42
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
a_table = cfg[4][2] -- "dummy.foobar", { z = 5, { "barfoo", {} } }

Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.

Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.

For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.

local old_event_handler
old_event_handler = register_wml_action("event",
function(cfg)
-- Get the plain text from the user.
local new_cfg = cfg.__literal
-- The expression below is equivalent to cfg.__parsed.first_time_only,
-- only faster. It is needed, since the first_time_only attribute may
-- reference variables.
local first = cfg.first_time_only
-- Modify the default behavior of first_time_only.
if first == nil then first = false end
new_cfg.first_time_only = first
-- Call the engine handler.
old_event_handler(new_cfg)
end
)

Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:

function get_child(cfg, name)
for i = 1, #cfg do
local v = cfg[i]
if v[1] == name then return v[2] end
end
end

Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:

if getmetatable(cfg) == "wml object" then cfg = cfg.__parsed end

The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal''' {{DevFeature1.9}}. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.

== Skeleton of a preload event ==

The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"

-- Define your global constants here.
-- ...

H.set_wml_var_metatable(_G)

-- Define your global functions here.
-- ...
>>
[/lua]
[/event]

It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:

[event]
name=preload
first_time_only=no
[lua]
code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >>
[/lua]
[/event]

== Remarks ==

The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.

function random(min, max)
if not max then min, max = 1, min end
wesnoth.fire("set_variable", { name = "LUA_random", rand = string.format("%d..%d", min, max) })
local res = wesnoth.get_variable "LUA_random"
wesnoth.set_variable "LUA_random"
return res
end

[[Category: Lua Reference|*]]
[[Category: WML Reference]]

LuaWML/Display

2011-12-09T20:17:56Z

Exasperation: Added wesnoth.set_dialog_active (available since 1.9.9)

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.get_time_of_day ====
{{DevFeature1.9}}

Returns schedule information. First parameter (optional) is the turn number for which to return the information, if unspecified: the current turn ($turn_number). Second argument is an optional table. If present, first and second fields must be valid on-map coordinates and all current time_areas in the scenario are taken into account (if a time area happens to contain the passed hex). If the table isn't present, the scenario main schedule is returned. The table has an optional third parameter (boolean). If true (default: false), time of day modifying units (such as MoL) are taken into account (if the passed hex happens to be affected). The units placement being considered is always the current one.

wesnoth.get_time_of_day(2, { 37, 3, true })

The function returns a table with these named fields:
* '''id''': string (as in [time])
* '''lawful_bonus''': integer (as in [time])
* '''bonus_modified''': integer (bonus change by units)
* '''image''': string (tod image in sidebar)
* '''name''': translatable string
* '''red, green, blue''': integers (color adjustment for this time)

==== wesnoth.highlight_hex ====

{{DevFeature1.9}}

Highlights the given location in the game map, and the unit stationed on it if applicable.

wesnoth.highlight_hex(unit.x, unit.y)

==== wesnoth.select_hex ====

{{DevFeature1.9}}

Selects the given location in the game map.

wesnoth.select_hex(12, 34)

==== wesnoth.scroll_to_tile ====

{{DevFeature1.9}}

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.play_sound ====

{{DevFeature1.9}}

Plays the given sound file, possibly repeating it a few more times.

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

{{DevFeature1.9}}

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

{{DevFeature1.9}}

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

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

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

{{DevFeature1.9}}

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

{{DevFeature1.9}}

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_active ====

{{DevFeature1.9}}

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

{{DevFeature1.9}}

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_canvas ====

{{DevFeature1.9}}

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

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.

==== wesnoth.get_displayed_unit ====

{{DevFeature1.9}}

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

{{DevFeature1.9}}

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

FormulaAI

2011-05-12T14:01:17Z

Exasperation: /* Formula Basics */

== Overview ==

The Wesnoth Formula AI is an attempt to develop an AI framework for Wesnoth that allows easy and fun development and modification of AIs for Wesnoth.

Wesnoth already has support for AIs written in Python, but writing AIs in Python has a couple of problems:

* it's still rather difficult, especially for a non-programmer, to develop an AI, even in Python
* Python is insecure; a malicious trojan horse Python script masquerading as an AI could do untold damage

The Wesnoth Formula AI aims to create a fairly simple, pure functional language which allows one to implement an AI. It also aims to allow AIs to be tweaked and modified by people with relatively little technical skill; anyone who can use WML should also be able to use the Formula AI to tweak an AI to make the AI in a scenario behave how they want.

The Wesnoth Formula AI is currently in an experimental stage of development. One can play with it and develop a rudimentary AI. Feedback is appreciated.

To develop an AI using the Formula AI, set ai_algorithm=formula_ai in [side].

== How formulas get called ==

=== Formulas Command Line ===

To attempt to make it convenient to debug formulas, one can run formulas from within Wesnoth, and see the results. To run a formula, just start game and type 'f'. A command textbox will appear, where you can type a formula, and the results will be printed. For instance, typing

8 + 4

will result in "12" appearing on the screen. You can now use Wesnoth like a calculator. :-)

=== Side-wide formulas ===
The first way to get a formula called is to assign it to a [side] in a WML map. This formula will be called every turn, so it is best used for very simple sides (a couple of special units which should have semi-scripted moves, or a simple handling followed by calls to the standard C++ AI)

To use the Formula AI, one should put an [ai] tag inside the [side] tag. Inside this [ai] tag, one should specify the 'move' attribute to be a formula which specifies what movement the AI will make. Each time it's the AI's move, this formula will be run, and the move it results in will be executed. Then the formula will be run again; it'll continue to be run until it stops producing a valid move, at which point the AI will end its turn. Alternatively there is a command that the formula may return which will make it end its turn immediately.

A sample AI which does nothing but recruit Wolf Riders is as follows:

[side]
...
[ai]
ai_algorithm=formula_ai
move="recruit('Wolf Rider')"
[/ai]
[/side]

=== Unit Formulas ===

You can specify a formula for any kind of unit. This is a simple way of doing it:

[unit]
...
[ai]
formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
[/ai]
[/unit]

Custom unit formulas are executed first at the begining of side's turn. Above formula will simply move unit one hex to the north every turn. Note how "me" keyword allows access to unit itself.

If you need to execute unit formulas in a specific order, you can set a priority:

[unit]
...
[ai]
formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
priority=10
[/ai]
[/unit]

Units with highest priority get their formula executed first.

You can also define AI unit-specific variables and use them in you formulas:

[unit]
...
[ai]
formula="if(attack, attack, move(me.loc, me.vars.guard_loc) )
where attack = choose(filter(attacks, units = [me.loc] and distance_between(me.vars.guard_loc, target) <= me.vars.guard_radius and unit_at(target).side=me.vars.hostile_side-1 ), avg_damage_inflicted)"

[vars]
guard_radius=3
guard_loc="loc(8,5)"
hostile_side=1
[/vars]
[/ai]
[/unit]

This formula will get location position from variable guard_loc and make sure that unit attacks only opponent from side 1 (value specified by hostile_side variable) which is 3 hexes (guard_radius) or less from guard_loc.

Types of variables that are supported:
*number:
variable=3
*text (important: note the ' ' within " "):
name="'I am variable'"
*list:
number_list=[ 1, 2, 3]
* map:
map=[ 'Elvish Archer' -> 70, 'Elvish Shaman' -> 60 ]
*location:
place="loc(X,Y)"

=== Candidate move evaluation ===
==== Overview ====
Units in wesnoth have all sort of special abilities, special powers and special usages. Thus, it was needed to have an easy way to describe special behaviour for special units. Adding an formula to a unit only partially solves the problem. It allows easily to have special units (like ennemy heroes) have special behaviour but not normal units with special powers to to behave smartly.

Candidate moves are a way to have formula that will

* evaluate a given situation
* see if they are able to provide "special moves" for the case they know how to handle
* give a move to do if the situation match their condition

==== Evaluation Algorithm ====

Each side will have some candidate move blocks made of
* a name for the move
* a type (see below for description of the different types and how they are called)
* a formula returning a score for the move
* a formula returning the move to do

The engine will run the following pseudo-code

while (a formula returned a score greatern than 0) {
foreach (registered candidate move) {
foreach (set of parameters for that candidate move's type) {
call the evaluation formula, note the score returned
}
}
if (the highest score returned was greater than 0) {
call the candidate move that returned the highest score with the corresponding set of parameters
}
}

in other word, we evaluate all candidate moves, then run the candidate move with the highest score, then re-evaluate everything, until no candidate move wants to play anymore

==== Syntax ====
to add a new candidate move you should add '''[register_candidate_move]''' blocks within the '''[ai]''' block.

Each block will describe a candidate move and must have the following fields

* ''name'' : the name of this candidate block
* ''type'' : see the paragraph about types below, this describe the implicite variables that the formulas will be called with
* ''evaluation'' : a formula returning an integer. This number reflects how good the move is compared to other moves. Values of zero will mean the move is not a good idea and should be skipped
* ''action'' : A formula that will be called if that candidate move is the best one
==== Candidate move types ====

there are two types of candidate moves

* '''attack''' : these are called once for every pair <me,target> where me is a variable set to a unit on the AI side, and target is a variable set to an ennemy unit that "me" can reach
* '''movement''' : these are called once for every unit on the AI side, the "me" variable is set to the corresponding unit

=== Summary : a typical AI turn ===

An AI turn will run the following formulas. Any formula returning an "end turn" move will (of course) finish the turn. But assuming this doesn't happen :
* All unit formulas are called once
* All candidate moves are evaluated and played
* All ''move='' formulas are called until they don't return valid moves
* If no ''move='' formula is provided, we drop automatically to C++
* Turn is ended.

Note that this means that you have to explicitely call "fallback" if you want the C++ AI to finish your moves after a side-wide formula

== Formula Basics ==

* The Formula language supports basic arithmetic operations, such as: +, -, *, /, % and ^. It supports integers and decimal/floating point numbers, but operations will default to integer math unless operands are specified as floating point. For example:

4 + 8*7 #evaluates to 60
(4 + 8)*7 #evaluates to 84
8 % 6 #evaluates to 2
5 / 2 #evaluates to 2
5.0 / 2 #evaluates to 2.5
5 / 2.0 #evaluates to 2.5
3 ^ 2 #evaluates to 9

* It also supports equality, = and !=, and comparison operators, <, >, <=, and >=. 'false' values are 0 (integer) and null. Other values are true. It also supports common operators such as and, or, and not:

2 = 4 #evaluates to 0
2 <= 3 #evaluates to 1
0 != 1 #evaluates to 1
not 4 #evaluates to 0
not 0 #evaluates to 1
(2 < 4) and (3 > 6) #evaluates to 1 and 0 which evaluates to 0
(2 < 4) or (3 > 6) #evaluates to 1 or 0 which evaluates to 1

* Formula language supports also 'dice' operator 'd'. Example usage is:

3d5

Which will give you one of results of rolling three five-sided dice (so random number between 3 and 15). NOTE: We encourage you to use this operator only when it is really needed. In most cases, you should not base the AI decisions on random results except for scenario replayability purposes.

== Data Types ==

Formula System supports different types of data, which can be stored as a variables and are used in evaluations:

* Numbers: like 0, 1, 2 etc. Floating-point numbers are not supported. 0 is equal to logical 'false', any other number is 'true'.

* Text strings:

'this is a text string'

* Lists: A list is a sequence of values. For example, ai.my_units is a list of unit objects. A list is represented as square brackets, [], surrounding a comma-seperated list. For instance:

[4, 8, 7]

is a list of three numbers, and

[]

is a empty list. Various functions can operate on lists.

To acces one particular element of a list we can use operator [], for example:

my_list[0]

Returns first element from the my_list, so:

[ 10, 20, 30, 40][2]

Returns

30

* Maps: A map is a sequence of pairs, each pair is a key and assigned to it value. For example:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ]

Is a map which consist of two pairs, first one assigns to the text string 'Elvish Fighter' the value 50, second one assigns 60 to the 'Elvish Archer' string.

To access value assigned to the key, we can use operator []:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ][ 'Elvish Fighter' ]

Above example returns

50

== AI Formula Language ==

=== Overview ===

The formula language must be able to access information about the scenario being played to make intelligent decisions. Thus there are various 'inputs' that one may access. A simple example of an input is the turn number one is on, given by the input, 'turn'. Try bringing up the formula command line using 'f' and then type in

turn

The AI will print out the current turn number the game is on.

The 'turn' input is a simple integer. However, some inputs are complex types which contain other inputs, or which may be lists of inputs. For instance, the input 'my_units' contains a list of all the AI's units.

A complex input such as a unit will contain a variety of inputs inside it. If one has a unit input, called 'u' for instance, one can access the 'x' co-ordinate of that unit by using u.loc.x -- u.loc accesses the 'location' object inside the 'unit' object, and the 'location' object contains 'x' and 'y' inputs inside it, which are the x and y co-ordinate of the unit.
=== Available variables ===
these are variables that you can call in an AI formula or from the command line.

Some of these variables are complicated data structues, calling their name from the formula command line will allow you to easily see their content

use the '''dir''' and '''debug_print''' to inspect the variables

to get a coplete list, use the
dir(self)
command

* ''attacks'' a list of all possible attacks
NOTE: this variable returns a list of all possible attacks (including attack combinations - attacking a single enemy unit with several units) , which is immediately treated as list of attack orders, which is evaluated (so, evaluation of this variable results in attacks being made). If you want to get the list without such evaluation, wrap it inside the array, "[attacks]". If you want to get the first attack, wrap it inside the array twice, "[[attacks[0]]"
]

* ''my_attacks'' a list of all possible attacks. It returns slightly different list then ''attacks''. I.e. when only two units (attacker and dedenter) are on the board ''attacks'' return one attack, from the position with the highest defence and ''my_attacks'' returns all 6 attacks from all adjacent tiles.
* ''my_side'' global variables describing your own side
* ''teams'' all the data about all the teams
* ''turn'' the current turn number
* ''time_of_day'' the current time of day
* ''keeps'' all keep locations
* ''vars'' all localy set varables using the set_var function
* ''allies'' a list of all sides that are friendly
* ''ennemies'' a list of all sides that are enemy
* ''my_moves'' a list of all my moves
* ''enemy_moves'' a list of all enemy moves
* ''my_leader'' our leader unit
* ''my_recruits'' the list of units that can be recruited by us
* ''recruits_of_side'' foreach side the list of units that can be recruited
* ''units'' the complete list of all units
* ''units_of_side'' foreach side, a list of all owned units
* ''my_units'' the complete list of all units owned by the current player
* ''enemy_units'' all units that are enemy to the current player
* ''villages'' all the villages on the map
* ''my_villages'' all the villages owned by the current player
* ''villages_of_side'' for each side, the list of villages owned
* ''enemy_and_unowned_villages'' all villages that you don't own
* ''map'' all the data about the map

=== Built-in functions ===
The formula language contains a large number of built-in functions which allow you to carry out all kinds of complex tasks. List of these functions, usage and simple examples can be found [http://www.wesnoth.org/wiki/FormulaAI_Functions here].

=== Custom Functions ===

* You can define your own functions. A function is a formula which takes some inputs as parameters. Suppose we wanted to define a function that puts some value on a unit, we might add the following to the [ai] tag:

[function]
name=value_unit
inputs="unit"
formula="unit.hitpoints + unit.level*4"
[/function]

This has defined a new function which takes a 'unit' as an input, and runs the given calculation over it.

* We can have multiple inputs in our functions, to define them, just create comma-separated inputs list:

inputs="attacker,defender"

This has defined a new function which takes both 'attacker' and 'defender' as an inputs.

* Sometimes, we use one of our inputs really often in our function - to make our life easier we can make its members (inputs) directly accessible from within the formula. This is improved version of function from above:

[function]
name=value_unit
inputs="unit*"
formula="hitpoints + level*4"
[/function]

As you can see, if we define input with a * char at the end, we make it a 'default input' for a formula. Note, that you can define only one default input per function.

* It is important to know difference between formulas defined in custom functions, and formula defined by a 'move=' in a [ai] tag. For example, if we want to get info about leader, we write in formula 'my_leader' - which acces member of the AI. To be able to use 'my_leader' in custom functions we have to add 'ai' as an input for our function:

inputs="ai"

allows us to access leader info by writing 'ai.my_leader', or:

inputs="ai*"

allows us to access leader info by simply writing 'my_leader'

* You can also use 'def' [[#Keywords|keyword]] to define custom functions

=== Comments ===

Comments in Formula AI scripts are enclosed by # #:

#Define opening move#
def opening(ai*)
if(turn = 1,
move(loc(11,23), loc(14,22)),
[])

Comments may also be included at the end of a line:

def opening(ai*)
if(turn = 1,
move(loc(11,23), loc(14,22)), #capture village#
[]) #do nothing#

and they may also be used inline:

def opening(ai*)
if(turn = 1,
move(loc(11,23) #my_leader#, loc(14,24) #closest village#),
[] #do nothing# )

== Keywords ==

The formula language has some reserved keywords to provide primitive functionality. Currently the following keywords are defined:

* where: This keyword is used to defining statements in formulas. You can define multiple comma-separated statements. Syntax:

<formula> where <comma-separated list of statements>

For example formula:

a + b where a = 2, b = 4

will give as result 6.

* functions: Returns a list of all built-in and custom functions available to the AI

* def: This keyword creates functions using the syntax:

def function_name(arg1, arg2, ....) function_body

For example,

def sum(x,y) x + y

creates a function sum taking two arguments and returns their sum.

== Files and formulas ==

You can easily split your formulas between different files and include them when necessary. For example:

[unit]
...
formula={my_unit_formula.fai}
[/unit]

Will look for unit formula in the my_unit_formula.fai file.

Although it is not mandatory, we advocate to use following syntax in your fai files:

faifile '<filename>'
...
faiend

This makes formula system know which file it is working with now, and gives you improved error reporting, which is often really helpful. Valid syntax for my_unit_formula.fai would be:

faifile 'my_unit_formula.fai'
...
faiend

== Tool Support ==

=== ctags ===

For some rudimentary support for exuberant ctags, add the following to .ctags (or create the file if it doesn't exist):

--langdef=formulaai
--langmap=formulaai:.fai
--regex-formulaai=/^def[ \t]*([a-zA-Z0-9_]+)/\1/d,definition/

This is especially nice when used with an editor or plugin with ctags support, such as Taglist for Vim.

=== Vim ===

====Syntax Highlighting====

Follow these steps to enjoy vim syntax highlighting support for Formula AI.

# Grab the Formula AI vim syntax file, [http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/tools/vim/formulaai.vim formulaai.vim].
# Copy formulaai.vim to .vim/syntax
# Add the following to .vimrc :
autocmd! BufRead,BufNewFile *.fai setfiletype formulaai

====Taglist Support====

First you will need the very nice [http://www.vim.org/scripts/script.php?script_id=273 taglist plugin]. Follow the link for downloads and install directions if you don't already have it installed.

Next, you'll need Formula AI support for exuberant ctags, follow the instructions in the [[#ctags|ctags]] section.

Once you have all that, simply add the following line to your .vimrc:

let tlist_formulaai_settings = 'formulaai;d:definition'

To test it all out, open a Formula AI script file and enter the command
:Tlist

You should now have some nice highlighting and be able to easily navigate through formula, enjoy!

[[Category:Development]]

[[Category:Development]]

LuaWML/Display

2011-05-01T15:43:50Z

Exasperation: /* wesnoth.show_dialog */

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.hilight_hex ====

{{DevFeature1.9}}

Highlights the given location in the game map, and the unit stationed on it if applicable.

wesnoth.hilight_hex(unit.x, unit.y)

==== wesnoth.select_hex ====

{{DevFeature1.9}}

Selects the given location in the game map.

wesnoth.select_hex(12, 34)

==== wesnoth.scroll_to_tile ====

{{DevFeature1.9}}

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.play_sound ====

{{DevFeature1.9}}

Plays the given sound file, possibly repeating it a few more times.

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

{{DevFeature1.9}}

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

{{DevFeature1.9}}

Displays a dialog box described by a WML table and returns the integer value associated to the button pressed by the user. The content of the WML table is described at [[GUIWidgetInstanceWML]]; it should at least contain the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''.

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

{{DevFeature1.9}}

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

{{DevFeature1.9}}

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

{{DevFeature1.9}}

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_canvas ====

{{DevFeature1.9}}

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

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.

==== wesnoth.get_displayed_unit ====

{{DevFeature1.9}}

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

{{DevFeature1.9}}

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

DirectActionsWML

2009-10-03T17:51:33Z

Exasperation: /* Direct actions */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
** '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes.
** '''linger_mode''': whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
** '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
** '''end_text''': Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
** '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].
** {{Short Note:Predefined Macro|GENERIC_UNIT}}
** '''to_variable''': spawn directly into a variable instead of on the map.
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
** '''clear_shroud''': should shroud be cleared on arrival
** '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
** '''ignore_passability''': {{DevFeature}} normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "yes" permits it.
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
** '''layer''': (overlay|base|both, default=both) only change the specified layer.
** '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
** '''x''' ,'''y''': override unit location
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** '''hidden''': a boolean string specifying whether side is shown in status table.
** '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
** '''switch_ai''': {{DevFeature}} replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
** '''share_maps''': {{DevFeature}} change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
** '''share_view''': {{DevFeature}} change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
** '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'last breath' and 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event.
* '''[unpetrify]''': Unpetrifies all units that match the filter. {{DevFeature}}; in 1.6 and earlier this is '''[unstone]'''.
** [[StandardUnitFilter]] all units matching the filter will be unpetrified. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unpetrified.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* '''[heal_unit]''': heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.
* '''[time_area]''': how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
** [[StandardLocationFilter]]: the locations to affect.
** [[TimeWML]]: the new schedule.
** '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.
** '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.

* '''[end_turn]''': end the current side's turn. {{DevFeature}} The current event is finished before the turn is ended.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]