The Battle for Wesnoth Wiki - User contributions [en]

LuaWML

2011-01-15T12:42:20Z

Silene: Added missing links

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

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.hilight_hex|wesnoth.hilight_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_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]]

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

LuaWML/Display

2011-01-15T12:40:29Z

Silene: Mentioned wesnoth.get_displayed_unit and wesnoth.theme_items

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 a '''[grid]''' child.

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.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" })

LuaWML/Units

2011-01-15T12:24:15Z

Silene: Mentioned transform_unit and writable experience

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''hitpoints''', '''experience''': integer (read/write) {{DevFeature1.9}}
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write) {{DevFeature1.9}}
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields) {{DevFeature1.9}}
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied {{DevFeature1.9}}
* '''valid''': string or nil (read only) {{DevFeature1.9}}
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

The term "proxy", here in particular "proxy unit", means that the variable retrieved in the lua code (with get_units for example) is an accessor (reference) to the C++ object which represents that unit. This is very different from unit variables obtained by [store_unit] in wml. The fields marked as "writable" above can be modified without the need to use put_unit afterwards. This same reason explains that modifications to the unit from outside the lua code (like [kill] invalidating the proxy unit) have immediate effect on the lua code's proxy unit variable (with the exception of private proxy units).

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

{{DevFeature1.9}}

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

{{DevFeature1.9}}

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

{{DevFeature1.9}}

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

{{DevFeature1.9}}

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

{{DevFeature1.9}}

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

{{DevFeature1.9}}

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

{{DevFeature1.9}}

Returns true if the given ability is active for the unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====

Returns an array containing all the unit type IDs the engine knows about.

local unit_types = wesnoth.get_unit_type_ids()
wesnoth.message(string.format("%d unit types registered. First one is %s.", #unit_types, unit_types[1]))

==== wesnoth.get_unit_type ====

Returns the unit type with the corresponding ID.

local lich_cost = wesnoth.get_unit_type("Ancient Lich").cost

Unit types are proxy tables with the following fields:
* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

==== wesnoth.unit_types ====

{{DevFeature1.9}}

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

local function display_stats(n, t)
wesnoth.message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

==== wesnoth.transform_unit ====

{{DevFeature1.9}}

Changes the type of a unit and adjust attributes accordingly. Note that hitpoints might be modified accordingly to the unit type.

local ev = wesnoth.current.event_context
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]
local old_hp = u.hitpoints
wesnoth.transform_unit(u, "Skeleton")
u.hitpoints = old_hp
u.status.poisoned = false

LuaWML/Misc

2010-12-26T11:40:08Z

Silene: Mentioned second argument of wesnoth.synchronize_choice.

This page describes miscellaneous [[LuaWML]] objects and helpers.

==== wesnoth.game_config ====

Contrarily to the other values of the ''wesnoth'' table, ''game_config'' is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:

* '''version''': string (read only)
* '''base_income''': integer (read/write)
* '''village_income''': integer (read/write)
* '''poison_amount''': integer (read/write)
* '''rest_heal_amount''': integer (read/write)
* '''recall_cost''': integer (read/write)
* '''kill_experience''': integer (read/write)
* '''debug''': boolean (read only)

-- Healing, poison, and regeneration, are a bit weak? Let's boost them!
wesnoth.game_config.poison_amount = 15

==== wesnoth.current ====

As with ''game_config'', ''current'' is a proxy table. Its fields are getter for game-related properties:

* '''side''': integer (read only)
* '''turn''': integer (read only)
* '''event_context''': WML table with attributes ''name'', ''x1'', ''y1'', ''x2'', ''y2'', and children ''weapon'', ''second_weapon'', describing the trigger for the current event.

wesnoth.message(string.format("Turn %d, side %d is playing.", wesnoth.current.turn, wesnoth.current.side))

==== wesnoth.synchronize_choice ====

{{DevFeature1.9}}

Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called. An optional second function can be passed; if present, it will be used instead of the first one when the client happens to be an AI (hence not enable to interact with a user interface).

local result = wesnoth.synchronize_choice(function()
-- Called only on the client handling the current side, if it is a human.
local choice = 0
wesnoth.show_dialog(some_dialog_cfg, nil, function() choice = wesnoth.get_dialog_value "some_list" end)
return { value = choice }
end, function()
-- Called only on the client handling the current side, if it is an AI.
return { value = math.random(some_list_size) }
end)
wesnoth.message(string.format("Selected item: %d", result.value))

==== wesnoth.get_image_size ====

{{DevFeature1.9}}

Returns the width and height of an image.

local w, h = wesnoth.get_image_size "units/transport/galleon.png"

==== helper.set_wml_tag_metatable ====

Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.

T = helper.set_wml_tag_metatable {}
W.event { name = "new turn", T.message { speaker = "narrator", message = "?" } }

==== helper.modify_unit ====

Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MODIFY_UNIT] macro.

helper.modify_unit({ id="Delfador" }, { moves=0 })

==== helper.move_unit_fake ====

Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MOVE_UNIT] macro.

helper.move_unit_fake({ id="Delfador" }, 14, 8)

==== helper.rand ====
{{DevFeature1.9}}

(A shortcut to set_variable's rand= since math.rand is an OOS magnet and therefore disabled.) Pass a string like you would to set_variable's rand=.

create a random unit at (1, 1) on side=1 :
wesnoth.put_unit(1, 1, { type = helper.rand("Dwarvish Fighter,Dwarvish Thunderer,Dwarvish Scout") })

LuaWML

2010-12-24T13:19:36Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.hilight_hex|wesnoth.hilight_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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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#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

LuaWML/Misc

2010-12-24T13:18:07Z

Silene: Added wesnoth.get_image_size

This page describes miscellaneous [[LuaWML]] objects and helpers.

==== wesnoth.game_config ====

Contrarily to the other values of the ''wesnoth'' table, ''game_config'' is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:

* '''version''': string (read only)
* '''base_income''': integer (read/write)
* '''village_income''': integer (read/write)
* '''poison_amount''': integer (read/write)
* '''rest_heal_amount''': integer (read/write)
* '''recall_cost''': integer (read/write)
* '''kill_experience''': integer (read/write)
* '''debug''': boolean (read only)

-- Healing, poison, and regeneration, are a bit weak? Let's boost them!
wesnoth.game_config.poison_amount = 15

==== wesnoth.current ====

As with ''game_config'', ''current'' is a proxy table. Its fields are getter for game-related properties:

* '''side''': integer (read only)
* '''turn''': integer (read only)
* '''event_context''': WML table with attributes ''name'', ''x1'', ''y1'', ''x2'', ''y2'', and children ''weapon'', ''second_weapon'', describing the trigger for the current event.

wesnoth.message(string.format("Turn %d, side %d is playing.", wesnoth.current.turn, wesnoth.current.side))

==== wesnoth.synchronize_choice ====

{{DevFeature1.9}}

Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called.

local result = wesnoth.synchronize_choice(function()
-- called only on the client handling the current side
local choice = 0
wesnoth.show_dialog(some_dialog_cfg, nil, function() choice = wesnoth.get_dialog_value "some_list" end)
return { value = choice }
end)
wesnoth.message(string.format("Selected item: %d", result.value))

==== wesnoth.get_image_size ====

{{DevFeature1.9}}

Returns the width and height of an image.

local w, h = wesnoth.get_image_size "units/transport/galleon.png"

==== helper.set_wml_tag_metatable ====

Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.

T = helper.set_wml_tag_metatable {}
W.event { name = "new turn", T.message { speaker = "narrator", message = "?" } }

==== helper.modify_unit ====

Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MODIFY_UNIT] macro.

helper.modify_unit({ id="Delfador" }, { moves=0 })

==== helper.move_unit_fake ====

Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MOVE_UNIT] macro.

helper.move_unit_fake({ id="Delfador" }, 14, 8)

==== helper.rand ====
{{DevFeature1.9}}

(A shortcut to set_variable's rand= since math.rand is an OOS magnet and therefore disabled.) Pass a string like you would to set_variable's rand=.

create a random unit at (1, 1) on side=1 :
wesnoth.put_unit(1, 1, { type = helper.rand("Dwarvish Fighter,Dwarvish Thunderer,Dwarvish Scout") })

EffectWML

2010-12-20T09:55:03Z

Silene: Mentioned small portraits

{{WML Tags}}
== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit.
Any number of [effect] tags can be used to describe a complete
modification.
Modifications are permanent changes to a unit;
currently there is no way of removing a modification.
Effects can contain a [filter] tag which applies the effect only if it matches.
See [[StandardUnitFilter]] for details.

The following keys are always recognized for [effect]:
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list)
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list)
* '''times''': describes how much time the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML]] for explanations about defense_weight.
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitTypeWML]] for describing a unit type
* '''defense''': Sets unit chance to be hit in specific terrain (100 - defense value)
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[defense]''': a subtag that describes the new defense just like in [[UnitTypeWML]] for describing a unit type
* '''resistance''': Sets percent damage taken from combat
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitTypeWML]] for describing a unit type
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (0=disable, other=enable).
* '''profile''': customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': {{DevFeature1.9}} new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, {{DevFeature1.9}} and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
* '''image_mod''': modify the image path function([[ImagePathFunctionWML]]) of all the unit's frames.
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
* '''ellipse''': Change the image used for the unit's ellipse.
**'''ellipse''' : the new image to use.

== See Also ==

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

[[Category: WML Reference]]

SingleUnitWML

2010-12-20T09:54:25Z

Silene: Mentioned small portraits

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is not displayed to the player, but is to be used only for identifying and filtering for units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID.

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''' no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently.
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it).

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''small_profile''': {{DevFeature1.9}} sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'off', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The status of a unit is displayed on the Status Table; each status modification ''statusmod'' is represented by the image '''misc/statusmod.png'''.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'off'
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': this is set to 'yes' by ai_special=guardian and clearing it will allow the unit to act normally again.
** '''healable''': if set to 'no', the unit cannot be healed. {{DevFeature1.9}} ''healable'' is deprecated, use ''unhealable'' instead.
** '''unhealable''': {{DevFeature1.9}} if set to 'yes', the unit cannot be healed.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from the contents of the created unit to the scenario. Everything valid in [scenario][event]s is valid in [unit][event]s. warning: Contrarily to [unit_type][event]s, a [unit] tag performs variable substitution before creating the unit. This can be worked around by using $|variable_name syntax. note: [unit][event] does currently (1.8.3, 1.9.0-svn) not work.

== See Also ==

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

[[Category:WML Reference]]

ImagePathFunctions

2010-12-20T09:43:35Z

Silene: Added missing image modifiers

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

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

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

== Re-Color Function ==
May be used to change some colors in an image.
=== Syntax ===
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

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

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

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

== Palette-switch Function ==
May be used to change colors in an image following the specifications of a source and target (new) palette.
=== Syntax ===
'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

== Flip Function ==
May be used to flip an image horizontally and/or vertically
=== Syntax ===
'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizantally.

== Greyscale Function ==
May be used to greyscale the image (turn to black and white)
=== Syntax ===
'''~GS( )'''

== Crop Function ==
Extracts a rectangular section of an image file.
=== Syntax ===
'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width.
* ''height'': height of the selected region. Must be less than or equal to the original image's height.

== Blit Function ==
{{DevFeature1.9}}
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)
=== Syntax ===
'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

== Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.
=== Syntax ===
''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

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

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

Any color-shift is performed before changing opacity or desaturating the graphic (see ~O() and ~GS()).

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

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

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

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

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

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

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

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

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

== Overlay function ==
{{DevFeature1.9}}
Puts a time-of-day overlay on the image.
=== Syntax ===

'''~LIGHTEN()'''

'''~DARKEN()'''

== Background coloring function ==
{{DevFeature1.9}}
Sets the color of all the (semi-)transparent pixels of the image.
=== Syntax ===

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

== Null function ==
Does nothing.
=== Syntax ===

'''~NOP()'''

== Precedence of Functions ==

All functions are applied in left-to-right order, with the exception of RC() and TC() which are applied always before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(0,0,20,20)~CROP(10,10,10,10)" would result in taking a crop of the rectangle x=20;y=20;w=40;h=40 and then taking a crop from ''that'' rectangle as x=10;y=10;w=10;h=10 resulting in the area x=30;y=30;w=10;h=10 from the original graphic.

[[Category:WML Reference]]

UnitTypeWML

2010-12-19T21:02:41Z

Silene: Mentioned small_profile

{{WML Tags}}
== The [unit_type] tag ==

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

Unit animation syntax is described in [[AnimationWML]].

The following key/tags are recognized:
{| class="gallery" style="text-align:left;"
|-
! [advancefrom]
| the previous level unit on the advancement tree
- allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys: ** ''unit'' the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into. ** ''experience'' is optional. If present the experience needed to advance is set to this value. ({{DevFeature1.9}}, in 1.8 it can only be lowered) If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
|-
! advances_to
| When this unit has'' experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead.
|-
! alignment
| how the unit's damage should be affected by its lawful or liminal bonus (See [[TimeWML]]).
|-
! attacks
| the number of times that this unit can attack each turn.
|-
! cost
| when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited.
|-
! description
| (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
|-
! do_not_list
| Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools.
|-
! ellipse
| the ellipse image to display under the unit, which is normally team-colored. Default is the normal ellipse; "misc/ellipse-nozoc" is a dashed ellipse that should be used for units without zone of control.
|-
! experience
| When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
|-
! gender
| has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base.
|-
! hide_help
| determines if the unit type will appear in the in-game help. Possible values ''true'' and ''false'', defaults to ''false''.
|-
! hitpoints
| the maximum HP that the unit has, and the HP it has when it is created.
|-
! id
|the value of the ''type'' key for units of this type. An ''id'' should consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
WARNING : characters "$", "&", "*", "(" and ")" are illegal for use in the unit id and must be avoided because they might lead to corrupted saved games
|-
! level
| the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
|-
! movement
| the number of move points that this unit recieves each turn.
|-
! movement_type
| See '''movetype''', [[UnitsWML]]. Note that the tags '''movement_costs''', '''defense''', and '''resistance''' can be used to modify this movetype.
|-
! name
|(translatable) displayed in the Status Table for units of this type.
|-
! num_traits
| the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
|-
! profile
| the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cuttoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
|-
! small_profile {{DevFeature1.9}}
| the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
|-
! race
| See '''[race]''', [[UnitsWML]]. Also used in standard unit filter (see [[FilterWML]]).
|-
! undead_variation
| Which image to use when a unit of this type is killed by a unit with the plague ability.
|-
! usage
| the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field affects only recruitment, not the AI's behavior in combat; that is always computed from attack power and hitpoints.
|-
! zoc
| if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
|}
==== After max level advancement (AMLA) ====
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description (see [[DescriptionWML]]) displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement.
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]

==== Attacks ====
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (if ''name=x'' then ''icon=attacks/x.png'' is assumed unless present). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see '''[resistances]''', [[UnitsWML]]).
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory.
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, ''short'' and ''long'' will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
For those two following settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense

==== Animations ====
See [[AnimationWML]] for details on how to specify animations for the unit.

==== Other tags ====
* '''[base_unit]''': Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one. Subsequent attributes modify the copy. (1.3.7 and later versions only.)

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

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

* '''[variation]''': Defines a variation of a unit. Variations are invoked with an [effect] tag. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_name''': The name of the variation.
** '''inherit''': if ''yes'', inherits all the properties of the base unit. Defaults to no.
: All other keys in '''[variation]''' are the same as for '''[unit_type]''' itself.

* '''[male]''', '''[female]''': They can contain all '''[unit_type]''' tags, to specify a variation of different gender for a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit. Defaults to yes.

== See Also ==

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

[[Category: WML Reference]]

LuaWML

2010-11-05T22:25:28Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.hilight_hex|wesnoth.hilight_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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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#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]]

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

LuaWML/Pathfinder

2010-11-05T22:25:11Z

Silene: /* helper.adjacent_tiles */

This page describes the [[LuaWML]] functions and helpers for finding paths.

==== wesnoth.find_path ====

Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''max_cost''': if set, the pathfinder will ignore paths longer than its value
* '''ignore_units''': if set, the path will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side

The path is returned as a table of coordinate pairs. It contains both the source and destination tile if a path was found. The total cost of the path is also available as a second return value, if needed.

-- Display some items along the path from (x1,y1) to (x2,y2).
local u = wesnoth.get_units({ x = x1, y = y1 })[1]
local path, cost = wesnoth.find_path(u, x2, y2, { ignore_units = true, viewing_side = 0 })
if cost > u.moves then
wesnoth.message("That's too far!")
else
for i, loc in ipairs(path) do
wesnoth.fire("item", { x = loc[1], y = loc[2], image = "items/buckler.png" })
end
end

Instead of a parameter table, a cost function can be passed to the pathfinder. It will be called for all the tiles the computed path may possibly go through. It receives three arguments. The first two are the coordinates of the tile, the last one is the current cost for reaching that tile. The function should return a floating-point value that is the cost for entering the given tile. This cost should be greater or equal to one.

-- Count how many turns it would take, assuming the worst case (3 movement points per tile)
local max_moves = wesnoth.get_units({ x = x1, y = y1 })[1].max_moves
local path, cost = wesnoth.find_path(x1, y2, x2, y2,
function(x, y, current_cost)
local remaining_moves = max_moves - (current_cost % max_moves)
if remaining_moves < 3 then current_cost = current_cost + remaining_moves end
return current_cost + 3
end)
wesnoth.message(string.format("It would take %d turns.", math.ceil(cost / 3)))

==== wesnoth.find_vacant_tile ====

Returns the two coordinates of an empty tile the closest to the tile passed by coordinates. An optional unit (either a WML table or a proxy object) can be passed as a third argument; if so, the returned tile is such that the unit can go from the passed tile to it.

function teleport(src_x, src_y, dst_x, dst_y)
local u = wesnoth.get_units({x = src_x, y = src_y })[1]
local ut = u.__cfg
dst_x, dst_y = wesnoth.find_vacant_tile(dst_x, dst_y, u)
wesnoth.put_unit(src_x, src_y)
wesnoth.put_unit(dst_x, dst_y, ut)
end

==== wesnoth.find_reach ====

Returns all the locations reachable by a unit. The unit is given either by its two coordinates or by a proxy object. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''additional_turns''': if set to an integer n, the pathfinder will consider tiles that can be reached in n+1 turns
* '''ignore_units''': if set, the paths will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side
The locations are stored as triples in an array. The first two elements of a triple are the coordinates of a reachable tile, the third one is the number of movement points left when reaching the tile.

-- overlay the number of turns needed to reach each tile
local t = wesnoth.find_reach(u, { additional_turns = 8 })
local m = u.max_moves
for i,l in ipairs(t) do
wesnoth.fire("label", { x = l[1], y = l[2], text = math.ceil(9 - l[3]/m) })
end

==== helper.distance_between ====

Returns the distance between two tiles given by their coordinates.

local d = distance_between(x1, y1, x2, y2)

==== helper.adjacent_tiles ====

{{DevFeature1.9}}

Returns an iterator on the (at most six) tiles around a given location that are on the map. If the third argument is ''true'', tiles on the map border are also visited.

-- remove all the units next to the (a,b) tile
for x, y in helper.adjacent_tiles(a, b) do
wesnoth.put_unit(x, y)
end

LuaWML/Pathfinder

2010-11-05T22:24:21Z

Silene: Added helper.adjacent_tiles

This page describes the [[LuaWML]] functions and helpers for finding paths.

==== wesnoth.find_path ====

Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''max_cost''': if set, the pathfinder will ignore paths longer than its value
* '''ignore_units''': if set, the path will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side

The path is returned as a table of coordinate pairs. It contains both the source and destination tile if a path was found. The total cost of the path is also available as a second return value, if needed.

-- Display some items along the path from (x1,y1) to (x2,y2).
local u = wesnoth.get_units({ x = x1, y = y1 })[1]
local path, cost = wesnoth.find_path(u, x2, y2, { ignore_units = true, viewing_side = 0 })
if cost > u.moves then
wesnoth.message("That's too far!")
else
for i, loc in ipairs(path) do
wesnoth.fire("item", { x = loc[1], y = loc[2], image = "items/buckler.png" })
end
end

Instead of a parameter table, a cost function can be passed to the pathfinder. It will be called for all the tiles the computed path may possibly go through. It receives three arguments. The first two are the coordinates of the tile, the last one is the current cost for reaching that tile. The function should return a floating-point value that is the cost for entering the given tile. This cost should be greater or equal to one.

-- Count how many turns it would take, assuming the worst case (3 movement points per tile)
local max_moves = wesnoth.get_units({ x = x1, y = y1 })[1].max_moves
local path, cost = wesnoth.find_path(x1, y2, x2, y2,
function(x, y, current_cost)
local remaining_moves = max_moves - (current_cost % max_moves)
if remaining_moves < 3 then current_cost = current_cost + remaining_moves end
return current_cost + 3
end)
wesnoth.message(string.format("It would take %d turns.", math.ceil(cost / 3)))

==== wesnoth.find_vacant_tile ====

Returns the two coordinates of an empty tile the closest to the tile passed by coordinates. An optional unit (either a WML table or a proxy object) can be passed as a third argument; if so, the returned tile is such that the unit can go from the passed tile to it.

function teleport(src_x, src_y, dst_x, dst_y)
local u = wesnoth.get_units({x = src_x, y = src_y })[1]
local ut = u.__cfg
dst_x, dst_y = wesnoth.find_vacant_tile(dst_x, dst_y, u)
wesnoth.put_unit(src_x, src_y)
wesnoth.put_unit(dst_x, dst_y, ut)
end

==== wesnoth.find_reach ====

Returns all the locations reachable by a unit. The unit is given either by its two coordinates or by a proxy object. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''additional_turns''': if set to an integer n, the pathfinder will consider tiles that can be reached in n+1 turns
* '''ignore_units''': if set, the paths will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side
The locations are stored as triples in an array. The first two elements of a triple are the coordinates of a reachable tile, the third one is the number of movement points left when reaching the tile.

-- overlay the number of turns needed to reach each tile
local t = wesnoth.find_reach(u, { additional_turns = 8 })
local m = u.max_moves
for i,l in ipairs(t) do
wesnoth.fire("label", { x = l[1], y = l[2], text = math.ceil(9 - l[3]/m) })
end

==== helper.distance_between ====

Returns the distance between two tiles given by their coordinates.

local d = distance_between(x1, y1, x2, y2)

==== helper.adjacent_tiles ====

Returns an iterator on the (at most six) tiles around a given location that are on the map. If the third argument is ''true'', tiles on the map border are also visited.

-- remove all the units next to the (a,b) tile
for x, y in helper.adjacent_tiles(a, b) do
wesnoth.put_unit(x, y)
end

LuaWML/Location set

2010-11-05T22:18:40Z

Silene: Added locatoin_set:filter

{{DevFeature1.9}}

This page describes the [[LuaWML]] class for handling location sets and location maps. Objects of this class store a set of locations, with some optional data attached to each of them. Sets are just maps with ''true'' associated to each locations. It is not possible to associate ''nil'' to a location.

There is one main constructor [[#location_set.create]] and two auxiliary helper constructors [[#location_set.of_pairs]] and [[#location_set.of_wml_var]]. They are provided by the ''lua/location_set.lua'' file. All the other functions are methods from the class and they are available through the ':' operator only.

local location_set = wesnoth.require "lua/location_set.lua"
local a_set = location_set.create()
a_set:insert(17, 42, "something")
assert(a_set:get(17, 42) == "something")
local b_set = location_set.of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })
a_set:union(b_set)
a_set:to_wml_var "locations"

==== location_set.create ====

Returns an empty location set.

==== location_set.of_pairs ====

Returns a fresh location set filled by [[#location_set:of_pairs]].

==== location_set.of_wml_var ====

Returns a fresh location set filled by [[#location_set:of_wml_var]].

==== location_set:empty ====

Returns ''true'' if the set is empty.

local some_set = location_set.create()
assert(some_set:empty())

==== location_set:size ====

Returns the number of locations in the set.

some_set:insert(17, 42)
assert(some_set:size() == 1)

==== location_set:clear ====

Empties the content of the set.

some_set:clear()
assert(not some_set:get(17, 42))

==== location_set:get ====

Returns the data associated to the given location or ''nil'' if the location is not in the set.

some_set:insert(17, 42, "something")
assert(some_set:get(17, 42) == "something")

==== location_set:insert ====

Associates some data to the given location, or ''true'' if there is no data. Previous associated data is lost.

some_set:insert(17, 42)
assert(some_set:get(17, 42))

==== location_set:remove ====

Removes the given location from the set.

some_set:remove(17, 42)

==== location_set:of_pairs ====

Inserts all the locations from an array containing pairs (arrays with two elements). Previous content of the set is kept, unless overwritten by the content of the array.

some_set:of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })

==== location_set:of_wml_var ====

Inserts all the locations from a WML array. If a container has more than just ''x'' and ''y'' attributes, the remaining attributes and children are associated to the location as a WML table. Previous content of the set is kept, unless overwritten by the content of the WML array.

wesnoth.wml_actions.store_locations { variable="target", { "filter_adjacent", { x=17, y=42 } } }
some_set:of_wml_var "target"

==== location_set:to_pairs ====

Returns an array of pairs containing the locations of the set. Associated data are ignored. The order of the locations is not deterministic. If the order actually matters, the [[#location_set:to_stable_pairs]] method should be used instead.

local size = #(some_set:to_pairs())

==== location_set:to_stable_pairs ====

Returns an array of pairs containing the locations of the set. Contrarily to [[#location_set:to_pairs]], the locations are guaranteed to be sorted and hence synchronized over networks and replays.

==== location_set:to_wml_var ====

Fills a WML array with the content of the set. The order of the elements is safe.

local some_set = location_set.of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })
some_set:to_wml_var "locations"

==== location_set:union ====

Inserts the locations from the other set, possibly overwriting the associated of data the locations already present.

a_set:insert(17, 42, "nothing")
b_set:insert(17, 42, "something")
a_set:union(b_set)
assert(a_set:get(17, 42) == "something")

==== location_set:inter ====

Deletes the locations that are not in the other set. Associated data is kept intact if not removed.

a_set:insert(17, 42, "nothing")
b_set:insert(17, 42, "something")
a_set:inter(b_set)
assert(a_set:get(17, 42) == "nothing")

==== location_set:iter ====

Calls the given function on all the locations of the set. Iteration order is not deterministic. If the order actually matters, the [[#location_set:stable_iter]] method should be used instead.

some_set:iter(function(x, y, data) wesnoth.message(string.format("[%d,%d] = %s", x, y, type(data))) end)

==== location_set:stable_iter ====

Calls the given function on all the locations of the set. Contrarily to [[#location_set:iter]], the iteration is deterministic and hence safe for networks and replays.

some_set:stable_iter(function(x, y, data) wesnoth.message(string.format("[%d,%d] = %s", x, y, type(data))) end)

==== location_set:filter ====

Returns a new set containing all the locations of the set for which the given function returns true.

local new_set = old_set:filter(function(x, y, v)
local d = helper.distance_between(a, b, x, y)
return d <= 5 and v == "not found"
end)
wesnoth.message(string.format("%d traps in the neighborhood of (%d,%d)", new_set:size(), a, b))

==== location_set:union_merge ====

Calls the given function for all the locations of the other set and uses the returned values to fill the set. Note: the merge order is not stable.

-- merge the elements of s2 into s1 but preserve the old data of s1
function set_union(s1, s2)
s1:union_merge(s2, function(x, y, v1, v2) return v1 or v2 end)
end

-- remove from s1 the elements of s2
function set_difference(s1, s2)
-- the nested function is called s2:size() times; note: v2 is never nil
s1:union_merge(s2, function(x, y, v1, v2) return nil end)
end

==== location_set:inter_merge ====

Calls the given function for all the locations of the set and uses the returned values to replace it. Note: the merge order is not stable.

-- compute the intersection of s1 and s2 and put it into s1, but overwrite the data of s1
function set_inter(s1, s2)
s1:inter_merge(s2, function(x, y, v1, v2) return v2 or v1 end)
end

-- remove from s1 the elements of s2
function set_difference(s1, s2)
-- the nested function is called s1:size() times; note: v1 is never nil
s1:inter_merge(s2, function(x, y, v1, v2) return not v2 end)
end

LuaWML/Events

2010-11-05T22:08:48Z

Silene: Added on_event

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a WML action. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====

Registers the second argument as a handler for the given action tag. When the game encounters this tag an event, it fires the action handler and passes the content of the WML object as the first argument. If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.game_events ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

{{DevFeature1.9}}

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

{{DevFeature1.9}}

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

{{DevFeature1.9}}

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

{{DevFeature1.9}}

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

LuaWML

2010-11-05T22:04:36Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.hilight_hex|wesnoth.hilight_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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== 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: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#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]]

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

LuaWML/Tiles

2010-11-05T22:02:52Z

Silene: Added missing overlay functions

This page describes the [[LuaWML]] functions for handling terrains and tiles. The ''items'' library can be loaded by

items = wesnoth.require "lua/wml/items.lua"

==== wesnoth.get_map_size ====

Returns the width, the height, and the border size of the map.

local w,h,b = wesnoth.get_map_size()

==== wesnoth.get_terrain ====

Returns the terrain code for the given location.

local is_grassland = wesnoth.get_terrain(12, 15) == "Gg"

==== wesnoth.set_terrain ====

Modifies the terrain at the given location.

function create_village(x, y)
wesnoth.set_terrain(x, y, "Gg^Vh")
end
{{DevFeature1.9}}: An optional 4th parameter can be passed (layer): overlay, base or both, default both: Change the specified layer only. An optional 5th boolean parameter (replace_if_failed) can be passed, see the documentation of the [terrain] tag. To pass the 5th parameter but not the 4th, pass nil for the 4th.

==== wesnoth.get_terrain_info ====

Returns the terrain details for the given terrain code.

local is_keep = wesnoth.get_terrain_info(wesnoth.get_terrain(12, 15)).keep

Terrain info is a plain table with the following fields:
* '''id''': string
* '''name''', '''description''': translatable strings
* '''castle''', '''keep''', '''village''': booleans
* '''healing''': integer

==== wesnoth.get_selected_tile ====

Returns the two coordinates of the currently selected tile. This is mostly useful for defining command-mode helpers.

function chg_unit(attr, val)
local x, y = wesnoth.get_selected_tile()
if not x then wesnoth.message("Error", "No unit selected."); return end
helper.modify_unit({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)

==== wesnoth.get_locations ====

{{DevFeature1.9}}

Returns a table containing all the locations matching the given filter. Locations are stored as pairs: tables of two elements. See [[StandardLocationFilter]] for details about location filters.

-- replace all grass terrains by roads
for i,loc in ipairs(wesnoth.get_locations { terrain = "Gg" }) do
wesnoth.set_terrain(loc[1], loc[2], "Rr")
end

==== wesnoth.match_location ====

{{DevFeature1.9}}

Returns true if the given location passes the filter.

bool b = wesnoth.match_location(x, y, { terrain = "Ww", { "filter_adjacent_location", terrain = "Ds,*^Bw*" } })

==== wesnoth.add_tile_overlay ====

{{DevFeature1.9}}

Places a tile overlay (either an image or a halo) at a given location. The overlay is described by a table supporting the same fields as [[InterfaceActionsWML|[item]]].

wesnoth.add_tile_overlay(17, 42, { image = "items/orcish-flag.png" })

==== wesnoth.remove_tile_overlay ====

{{DevFeature1.9}}

Removes all the overlays at the given location. If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

wesnoth.remove_tile_overlay(17, 42, "items/orcish-flag.png")

==== items.place_image ====

{{DevFeature1.9}}

Places an image at a given location and registers it as a WML ''[item]'' would do, so that it can be restored after save/load.

local items = wesnoth.require "lua/wml/items.lua"
items.place_image(17, 42, "items/orcish-flag.png")

==== items.place_halo ====

{{DevFeature1.9}}

Behaves the same as [[#items.place_image]] but for halos.

==== items.remove ====

{{DevFeature1.9}}

Removes an overlay set by [[#items.place_image]] or [[#items.place_halo]]. If no filename is provided, all the overlays on a given tile are removed.

items.remove(17, 42, "items/orcish-flag.png")

LuaWML/Events

2010-10-30T16:03:01Z

Silene: Clarified semantic of WML actions with respect to their arguments.

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a WML action. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====

Registers the second argument as a handler for the given action tag. When the game encounters this tag an event, it fires the action handler and passes the content of the WML object as the first argument. If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.game_events ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

{{DevFeature1.9}}

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

{{DevFeature1.9}}

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

{{DevFeature1.9}}

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

{{DevFeature1.9}}

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

LuaWML/Pathfinder

2010-10-16T06:24:01Z

Silene: Fixed wrong description;

LuaWML/Units

2010-10-10T17:35:30Z

Silene: Mentioned unit variables.

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''hitpoints''': integer (read/write) {{DevFeature1.9}}
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write) {{DevFeature1.9}}
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields) {{DevFeature1.9}}
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied {{DevFeature1.9}}
* '''valid''': string or nil (read only) {{DevFeature1.9}}
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

The term "proxy", here in particular "proxy unit", means that the variable retrieved in the lua code (with get_units for example) is an accessor (reference) to the C++ object which represents that unit. This is very different from unit variables obtained by [store_unit] in wml. The fields marked as "writable" above can be modified without the need to use put_unit afterwards. This same reason explains that modifications to the unit from outside the lua code (like [kill] invalidating the proxy unit) have immediate effect on the lua code's proxy unit variable (with the exception of private proxy units).

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

{{DevFeature1.9}}

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

{{DevFeature1.9}}

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

{{DevFeature1.9}}

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

{{DevFeature1.9}}

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

{{DevFeature1.9}}

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

{{DevFeature1.9}}

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

{{DevFeature1.9}}

Returns true if the given ability is active for the unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====

Returns an array containing all the unit type IDs the engine knows about.

local unit_types = wesnoth.get_unit_type_ids()
wesnoth.message(string.format("%d unit types registered. First one is %s.", #unit_types, unit_types[1]))

==== wesnoth.get_unit_type ====

Returns the unit type with the corresponding ID.

local lich_cost = wesnoth.get_unit_type("Ancient Lich").cost

Unit types are proxy tables with the following fields:
* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

==== wesnoth.unit_types ====

{{DevFeature1.9}}

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

local function display_stats(n, t)
wesnoth.message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

LuaWML/Events

2010-10-03T15:59:08Z

Silene: Added rule about 'filter' naming.

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a WML action. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====

Registers the second argument as a handler for the given action tag. When the game encounters this tag an event, it fires the action handler and passes the content of the WML object as the first argument. If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: when calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the actual handler. So, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Another solution is to call [[#wesnoth.tovconfig]] and pass its result to the handler.

==== wesnoth.game_events ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

{{DevFeature1.9}}

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

==== helper.parsed ====

{{DevFeature1.9}}

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

{{DevFeature1.9}}

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

{{DevFeature1.9}}

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

LuaWML

2010-10-03T08:02:50Z

Silene: Added links to LuaWML:Location_set

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== 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: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#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]]

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

LuaWML/Location set

2010-10-03T07:55:56Z

Silene: Added description of the location_set class.

{{DevFeature1.9}}

This page describes the [[LuaWML]] class for handling location sets and location maps. Objects of this class store a set of locations, with some optional data attached to each of them. Sets are just maps with ''true'' associated to each locations. It is not possible to associate ''nil'' to a location.

There is one main constructor [[#location_set.create]] and two auxiliary helper constructors [[#location_set.of_pairs]] and [[#location_set.of_wml_var]]. They are provided by the ''lua/location_set.lua'' file. All the other functions are methods from the class and they are available through the ':' operator only.

local location_set = wesnoth.require "lua/location_set.lua"
local a_set = location_set.create()
a_set:insert(17, 42, "something")
assert(a_set:get(17, 42) == "something")
local b_set = location_set.of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })
a_set:union(b_set)
a_set:to_wml_var "locations"

==== location_set.create ====

Returns an empty location set.

==== location_set.of_pairs ====

Returns a fresh location set filled by [[#location_set:of_pairs]].

==== location_set.of_wml_var ====

Returns a fresh location set filled by [[#location_set:of_wml_var]].

==== location_set:empty ====

Returns ''true'' if the set is empty.

local some_set = location_set.create()
assert(some_set:empty())

==== location_set:size ====

Returns the number of locations in the set.

some_set:insert(17, 42)
assert(some_set:size() == 1)

==== location_set:clear ====

Empties the content of the set.

some_set:clear()
assert(not some_set:get(17, 42))

==== location_set:get ====

Returns the data associated to the given location or ''nil'' if the location is not in the set.

some_set:insert(17, 42, "something")
assert(some_set:get(17, 42) == "something")

==== location_set:insert ====

Associates some data to the given location, or ''true'' if there is no data. Previous associated data is lost.

some_set:insert(17, 42)
assert(some_set:get(17, 42))

==== location_set:remove ====

Removes the given location from the set.

some_set:remove(17, 42)

==== location_set:of_pairs ====

Inserts all the locations from an array containing pairs (arrays with two elements). Previous content of the set is kept, unless overwritten by the content of the array.

some_set:of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })

==== location_set:of_wml_var ====

Inserts all the locations from a WML array. If a container has more than just ''x'' and ''y'' attributes, the remaining attributes and children are associated to the location as a WML table. Previous content of the set is kept, unless overwritten by the content of the WML array.

wesnoth.wml_actions.store_locations { variable="target", { "filter_adjacent", { x=17, y=42 } } }
some_set:of_wml_var "target"

==== location_set:to_pairs ====

Returns an array of pairs containing the locations of the set. Associated data are ignored. The order of the locations is not deterministic. If the order actually matters, the [[#location_set:to_stable_pairs]] method should be used instead.

local size = #(some_set:to_pairs())

==== location_set:to_stable_pairs ====

Returns an array of pairs containing the locations of the set. Contrarily to [[#location_set:to_pairs]], the locations are guaranteed to be sorted and hence synchronized over networks and replays.

==== location_set:to_wml_var ====

Fills a WML array with the content of the set. The order of the elements is safe.

local some_set = location_set.of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })
some_set:to_wml_var "locations"

==== location_set:union ====

Inserts the locations from the other set, possibly overwriting the associated of data the locations already present.

a_set:insert(17, 42, "nothing")
b_set:insert(17, 42, "something")
a_set:union(b_set)
assert(a_set:get(17, 42) == "something")

==== location_set:inter ====

Deletes the locations that are not in the other set. Associated data is kept intact if not removed.

a_set:insert(17, 42, "nothing")
b_set:insert(17, 42, "something")
a_set:inter(b_set)
assert(a_set:get(17, 42) == "nothing")

==== location_set:iter ====

Calls the given function on all the locations of the set. Iteration order is not deterministic. If the order actually matters, the [[#location_set:stable_iter]] method should be used instead.

some_set:iter(function(x, y, data) wesnoth.message(string.format("[%d,%d] = %s", x, y, type(data))) end)

==== location_set:stable_iter ====

Calls the given function on all the locations of the set. Contrarily to [[#location_set:iter]], the iteration is deterministic and hence safe for networks and replays.

some_set:stable_iter(function(x, y, data) wesnoth.message(string.format("[%d,%d] = %s", x, y, type(data))) end)

==== location_set:union_merge ====

Calls the given function for all the locations of the other set and uses the returned values to fill the set. Note: the merge order is not stable.

-- merge the elements of s2 into s1 but preserve the old data of s1
function set_union(s1, s2)
s1:union_merge(s2, function(x, y, v1, v2) return v1 or v2 end)
end

-- remove from s1 the elements of s2
function set_difference(s1, s2)
-- the nested function is called s2:size() times; note: v2 is never nil
s1:union_merge(s2, function(x, y, v1, v2) return nil end)
end

==== location_set:inter_merge ====

Calls the given function for all the locations of the set and uses the returned values to replace it. Note: the merge order is not stable.

-- compute the intersection of s1 and s2 and put it into s1, but overwrite the data of s1
function set_inter(s1, s2)
s1:inter_merge(s2, function(x, y, v1, v2) return v2 or v1 end)
end

-- remove from s1 the elements of s2
function set_difference(s1, s2)
-- the nested function is called s1:size() times; note: v1 is never nil
s1:inter_merge(s2, function(x, y, v1, v2) return not v2 end)
end

LuaWML/Sides

2010-09-25T08:30:21Z

Silene: Template

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.get_side ====

Returns the team with given number.

local team = wesnoth.get_side(1)
team.gold = team.gold + 50

Teams are proxy tables with the following fields:
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
* '''total_income''': integer (read only)
* '''objectives''', '''user_team_name''': translatable strings (read/write)
* '''objectives_changed''': boolean (read/write)
* '''team_name''': string (read/write)
* '''controller''': string (read/write) {{DevFeature1.9}}
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"side"'''.

==== wesnoth.sides ====

{{DevFeature1.9}}

This is not a function but a table indexed by side numbers. Its elements are the proxy tables returned by [[#wesnoth.get_side]].

local team = wesnoth.sides[1]
team.gold = team.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_village_owner ====

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

Gives ownership of the village at the given location to the given side (or remove ownership if none).

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

{{DevFeature1.9}}

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== helper.all_teams ====

Returns an iterator over teams that can be used in a for-in loop.

for team in helper.all_teams() do team.gold = 200 end

LuaWML/Sides

2010-09-25T08:29:37Z

Silene: Mentioned controller side field.

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.get_side ====

Returns the team with given number.

local team = wesnoth.get_side(1)
team.gold = team.gold + 50

Teams are proxy tables with the following fields:
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
* '''total_income''': integer (read only)
* '''objectives''', '''user_team_name''': translatable strings (read/write)
* '''objectives_changed''': boolean (read/write)
* '''team_name''': string (read/write)
* '''controller''': string (read/write)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"side"'''.

==== wesnoth.sides ====

{{DevFeature1.9}}

This is not a function but a table indexed by side numbers. Its elements are the proxy tables returned by [[#wesnoth.get_side]].

local team = wesnoth.sides[1]
team.gold = team.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_village_owner ====

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

Gives ownership of the village at the given location to the given side (or remove ownership if none).

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

{{DevFeature1.9}}

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== helper.all_teams ====

Returns an iterator over teams that can be used in a for-in loop.

for team in helper.all_teams() do team.gold = 200 end

LuaWML/Units

2010-09-25T08:28:04Z

Silene: Mentioned the valid unit field.

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''hitpoints''': integer (read/write) {{DevFeature1.9}}
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write) {{DevFeature1.9}}
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields) {{DevFeature1.9}}
* '''valid''': string or nil (read only) {{DevFeature1.9}}
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

{{DevFeature1.9}}

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

{{DevFeature1.9}}

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

{{DevFeature1.9}}

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

{{DevFeature1.9}}

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

{{DevFeature1.9}}

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

{{DevFeature1.9}}

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

{{DevFeature1.9}}

Returns true if the given ability is active for the unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====

Returns an array containing all the unit type IDs the engine knows about.

local unit_types = wesnoth.get_unit_type_ids()
wesnoth.message(string.format("%d unit types registered. First one is %s.", #unit_types, unit_types[1]))

==== wesnoth.get_unit_type ====

Returns the unit type with the corresponding ID.

local lich_cost = wesnoth.get_unit_type("Ancient Lich").cost

Unit types are proxy tables with the following fields:
* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

==== wesnoth.unit_types ====

{{DevFeature1.9}}

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

local function display_stats(n, t)
wesnoth.message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

LuaWML

2010-09-05T18:23:21Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

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

LuaWML/Events

2010-09-05T18:21:53Z

Silene: Added helper functions

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a WML action. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====

Registers the second argument as a handler for the given action tag. When the game encounters this tag an event, it fires the action handler and passes the content of the WML object as the first argument. If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"''' See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

==== wesnoth.wml_actions ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: when calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the actual handler. So, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Another solution is to call [[#wesnoth.tovconfig]] and pass its result to the handler.

==== wesnoth.game_events ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

{{DevFeature1.9}}

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

==== helper.parsed ====

{{DevFeature1.9}}

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

{{DevFeature1.9}}

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

{{DevFeature1.9}}

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

LuaWML

2010-09-05T18:12:23Z

Silene: Avoided mentioning the merge between event context and [args]

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

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

LuaWML/Events

2010-09-01T21:02:26Z

Silene: Fixed namespace

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a WML action. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====

Registers the second argument as a handler for the given action tag. When the game encounters this tag an event, it fires the action handler and passes the content of the WML object as the first argument. If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"''' See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

==== wesnoth.wml_actions ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: when calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the actual handler. So, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Another solution is to call [[#wesnoth.tovconfig]] and pass its result to the handler.

==== wesnoth.game_events ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

LuaWML

2010-09-01T21:01:36Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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. The table also provides the fields '''x1''', '''y1''', '''x2''', and '''y2''', containing map locations, and the sub-tables '''weapon''' and '''second_weapon''' containing attacks, if relevant for the current event.

== 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 args = ...
if target_hex.is_set and
(args.x1 ~= target_hex.x or args.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 args = ...

loads the parameter of the script into the ''args'' local variable. Since it is a ''moveto'' event, the ''args'' 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
(args.x1 ~= target_hex.x or args.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
(args.x1 ~= wesnoth.get_variable("target_hex.x") or args.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]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

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

LuaWML/Events

2010-09-01T20:37:08Z

Silene: Mentioned hooks and clarified direct usage of functions from wml_actions

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a WML action. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====

Registers the second argument as a handler for the given action tag. When the game encounters this tag an event, it fires the action handler and passes the content of the WML object as the first argument. If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"''' See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

==== wesnoth.wml_actions ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: when calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the actual handler. So, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Another solution is to call [[#helper.tovconfig]] and pass its result to the handler.

==== wesnoth.game_events ====

{{DevFeature1.9}}

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(helper.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

StandardUnitFilter

2010-09-01T19:42:19Z

Silene: Improved [filter_wml] documentation

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [kill] and [have_unit]. See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given description. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this. See [[SingleUnitWML]].
* '''speaker''': alias for description
* '''type''': matches the unit's type name (can be a list of types)
* '''race''': the race of the unit type. Mainline races are listed in data/core/units.cfg
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless it is also found stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes. In Wesnoth 1.6.4 "yes" filters for units (visible or invisible) in visible locations. Filtering for unit (in)visibility requires "no".
** '''viewing_side''': the side(s) which you are checking if they are able to see (or not see) the unit. All sides listed here must pass the test. If no side is listed, it will check the visibility all enemy sides.
* '''[filter_wml]''': this is WML level filter for the unit. In it, you can filter on anything that is in the WML description of a unit. This description can be found in any savegame also in [[SingleUnitWML]]. If the filter encounters a nested '''[not]''' tag, the attributes and containers inside the tag should not match for the upper filter to match. Note: [filter_wml] is especially slow, unless it contains only a child [variables], which is used for matching variables stored inside the unit.
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''': standard unit filter; if present the correct number of adjacent units must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
* '''formula''': [[FormulaAI]] like formula returning a boolean. The unit filtered is an implicit variable in the call.
* '''lua_function''': the name of a [[LuaWML|Lua]] function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter.

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''description''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:
[kill]
[not]
id=Gwiti Ha'atel
[/not]
[not]
id=Tanar
[/not]
[/kill]
:And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:
[kill]
id=Gwiti Ha'atel
[or]
id=Tanar
[/or]
[/kill]

[[Category: WML Reference]]

ConditionalActionsWML

2010-08-15T04:59:42Z

Silene: Added warning

{{WML Tags}}

Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[:Category:ActionsWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[else]''': Contains [[:Category:ActionsWML|actions]] which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against.
This can be a comma separated list of values. {{DevFeature1.9}}
** [[:Category:ActionsWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[:Category:ActionsWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 1024 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[:Category:ActionsWML|actions]] that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[:Category:ActionsWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

=== [command] ===

This tag is more of an Unconditional Action: when it is encountered, the contents are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.

== Condition Tags ==

===True Condition Tags===
These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

; [have_unit]
: A unit with greater than zero hit points matching this filter exists.
:* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag. '''* Note:''' ''Does '''not''' check for matching units in the recall list!''
:* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".
:* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no') {{DevFeature1.9}}

; [have_location]
: A location matching this filter exists.
:* [[StandardLocationFilter]]: Selection criteria.
:* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

; [variable]
: Test the value of a WML [[VariablesWML|variable]] against another value.
:* '''name''': The name of the variable to test.
:* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
:** '''contains''': ''$name'' contains this string value.
:** '''equals''': ''$name'' is equal (string wise) to this value.
:** '''not_equals''': ''$name'' is not equal (string wise) to this value.
:** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
:** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value. '''*''' '''*''' Using equals is faster. The point of numerical_equals and boolean_equals is not performance, it's representation. For instance, "1" and "1.0" are not equal as strings but they are equal as numbers; and "yes" and "on" are not equal as strings but they are equal as booleans. (This also explains why equals is faster: it is a straightforward comparison that doesn't try to understand what you have written.)
:** '''greater_than''': ''$name'' is greater than this value.
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.
:** '''less_than''': ''$name'' is less than this value.
:** '''less_than_equal_to''': ''$name'' is less than or equal to this value.
:** '''boolean_equals''': ''$name'' has an equivalent boolean value. '''*'''
:** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value. '''*'''
====Boolean Values====
'''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''. These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0''' (and "'''uninitialized'''") These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)

'''Warning:''' Usage of "off", "on", integers, and floating-point numbers, as booleans, is deprecated and should be avoided to ensure forward-compatibility of WML with future versions.

=== Meta Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any others. Useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an [[:Category:ActionsWML|action]] to take place. (See [[AdvancedConditionalWML|Example]])
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: A condition which reverses the evaluation of the contained condition(s).
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

== See Also ==
* [[VariablesWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

LuaWML

2010-08-05T10:38:22Z

Silene: Added missing link

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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. The table also provides the fields '''x1''', '''y1''', '''x2''', and '''y2''', containing map locations, and the sub-tables '''weapon''' and '''second_weapon''' containing attacks, if relevant for the current event.

== 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 args = ...
if target_hex.is_set and
(args.x1 ~= target_hex.x or args.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 args = ...

loads the parameter of the script into the ''args'' local variable. Since it is a ''moveto'' event, the ''args'' 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
(args.x1 ~= target_hex.x or args.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
(args.x1 ~= wesnoth.get_variable("target_hex.x") or args.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.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

== 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. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { { "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]
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

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", { { "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

LuaWML/Units

2010-08-05T10:37:36Z

Silene: Added ability getter

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''hitpoints''': integer (read/write) {{DevFeature1.9}}
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write) {{DevFeature1.9}}
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields) {{DevFeature1.9}}
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists.

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

{{DevFeature1.9}}

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

{{DevFeature1.9}}

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

{{DevFeature1.9}}

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

{{DevFeature1.9}}

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

{{DevFeature1.9}}

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

{{DevFeature1.9}}

Modifies a given unit. The second argument is the type of the modification (either trait, object, or advance). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

{{DevFeature1.9}}

Returns true if the given ability is active for the unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====

Returns an array containing all the unit type IDs the engine knows about.

local unit_types = wesnoth.get_unit_type_ids()
wesnoth.message(string.format("%d unit types registered. First one is %s.", #unit_types, unit_types[1]))

==== wesnoth.get_unit_type ====

Returns the unit type with the corresponding ID.

local lich_cost = wesnoth.get_unit_type("Ancient Lich").cost

Unit types are proxy tables with the following fields:
* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

==== wesnoth.unit_types ====

{{DevFeature1.9}}

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

local function display_stats(n, t)
wesnoth.message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

LuaWML/Tiles

2010-08-05T05:06:57Z

Silene: Added link

This page describes the [[LuaWML]] functions for handling terrains and tiles.

==== wesnoth.get_map_size ====

Returns the width, the height, and the border size of the map.

local w,h,b = wesnoth.get_map_size()

==== wesnoth.get_terrain ====

Returns the terrain code for the given location.

local is_grassland = wesnoth.get_terrain(12, 15) == "Gg"

==== wesnoth.set_terrain ====

Modifies the terrain at the given location.

function create_village(x, y)
wesnoth.set_terrain(x, y, "Gg^Vh")
end

==== wesnoth.get_terrain_info ====

Returns the terrain details for the given terrain code.

local is_keep = wesnoth.get_terrain_info(wesnoth.get_terrain(12, 15)).keep

Terrain info is a plain table with the following fields:
* '''id''': string
* '''name''', '''description''': translatable strings
* '''castle''', '''keep''', '''village''': booleans
* '''healing''': integer

==== wesnoth.get_selected_tile ====

Returns the two coordinates of the currently selected tile. This is mostly useful for defining command-mode helpers.

function chg_unit(attr, val)
local x, y = wesnoth.get_selected_tile()
if not x then wesnoth.message("Error", "No unit selected."); return end
helper.modify_unit({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)

==== wesnoth.get_locations ====

{{DevFeature1.9}}

Returns a table containing all the locations matching the given filter. Locations are stored as pairs: tables of two elements. See [[StandardLocationFilter]] for details about location filters.

-- replace all grass terrains by roads
for i,loc in ipairs(wesnoth.get_locations { terrain = "Gg" }) do
wesnoth.set_terrain(loc[1], loc[2], "Rr")
end

==== wesnoth.match_location ====

{{DevFeature1.9}}

Returns true if the given location passes the filter.

bool b = wesnoth.match_location(x, y, { terrain = "Ww", { "filter_adjacent_location", terrain = "Ds,*^Bw*" } })

InternalActionsWML

2010-08-05T05:05:32Z

Silene: Removed redundant attributes

{{WML Tags}}

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.

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

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

* '''random''': 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. {{DevFeature1.9}} random is deprecated, use rand instead.

* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''

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

* '''name''': the name of the 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 unless the variable already contains data at that index. 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''': wether 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

* '''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_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', 'controller', 'village_gold' and 'recruit'.

* '''side''': the side whose information should be stored

* '''variable''': the name of the variable to store the information in

==== [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' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)

* '''side''': the side whose starting location is to be stored

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

* '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.

* '''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_villages] ====

Stores a series of locations of villages 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'.

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

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

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

=== [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 variable will be injected into the game as if they had been written out in WML form. ([[#.5Binsert_tag.5D_Example|See Example]])

*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.

*'''variable''': Name of the 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]]
* [[ConditionalWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

SingleUnitWML

2010-08-05T05:02:28Z

Silene: Mentioned uncovered. Removed obsolete devfeature marks.

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is not displayed to the player, but is to be used only for identifying and filtering for units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID.

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''' no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently.
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it).

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a default portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'off', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The status of a unit is displayed on the Status Table; each status modification ''statusmod'' is represented by the image '''misc/statusmod.png'''.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'off'
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': this is set to 'yes' by ai_special=guardian and clearing it will allow the unit to act normally again.
** '''healable''': if set to 'no', the unit cannot be healed. {{DevFeature1.9}} ''healable'' is deprecated, use ''unhealable'' instead.
** '''unhealable''': {{DevFeature1.9}} if set to 'yes', the unit cannot be healed.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from the contents of the created unit to the scenario. Everything valid in [scenario][event]s is valid in [unit][event]s. warning: Contrarily to [unit_type][event]s, a [unit] tag performs variable substitution before creating the unit. This can be worked around by using $|variable_name syntax. note: [unit][event] does currently (1.8.3, 1.9.0-svn) not work.

== See Also ==

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

[[Category:WML Reference]]

InterfaceActionsWML

2010-08-05T04:55:15Z

Silene: Mentioned SUF and clarified what hidden means

{{WML Tags}}
== Interface actions ==

Interface actions are actions that do not have an effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': zero or more '''[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
It can also be used to overwrite the starting objectives mid-scenario.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only. {{DevFeature}}

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.

== Other interface tags ==

The following tags are also action tags:
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
** '''x''', '''y''': the location to place the item.
** '''image''': the image (in ''images/'' as .png) to place on the hex.
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
** '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
** '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''[removeitem]''': removes any graphical items on a given hex
** '''x''', '''y''': the hex to remove items off
** '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)
* '''[print]''': displays a message across the screen. The message will disappear after a certain time.
** '''text''': (translatable) the text to display.
** '''size''': (default=12) the pointsize of the font to use
** '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
** '''type''': the type of the unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''gender''': the gender of the fake unit. Example: gender=female
** '''variation''': the variation of the fake unit. Example: variation=undead
* '''[move_units_fake]''': {{DevFeature1.9}} moves multiple images of units along paths on the map. These units are moved in lockstep.
** '''[fake_unit]''': A fake unit to move
*** '''type''': the type of unit whose image to use
*** '''x''': a comma-separated list of x locations to move along
*** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
*** '''side''': the side of the fake unit, used for team-coloring the fake unit
*** '''skip_steps''': the number of steps to skip before this unit starts moving
* '''[hide_unit]''': temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
** {{DevFeature1.9}}: '''[hide_unit]''' accepts a [[StandardUnitFilter]] as argument and can disable several units at once.
* '''[unhide_unit]''': stops the currently hidden units from being hidden.
** {{DevFeature1.9}}: '''[unhide_unit]''' accepts a [[StandardUnitFilter]] as argument.
* '''[scroll]''': Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
** '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''[scroll_to]''': Scroll to a given hex
** '''x''', '''y''': the hex to scroll to
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[scroll_to_unit]''' Scroll to a given unit
** [[StandardUnitFilter]]
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[sound]''': Plays a sound
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
** '''repeat''': repeats the sound for a specified additional number of times (default=0)
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
** '''id''': a unique identification key of the sound source
** '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
** '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
** '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
** '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
** '''check_shrouded''': {{DevFeature}} possible values "true" and "false" - if true the source will not play if its locations are shrouded
** '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
** '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
** '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
** '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)
* '''[remove_sound_source]''': Removes a previously defined sound source.
** '''id''': the identification key of the sound source to remove
* '''[music]''': Switches to playing different music
** '''name''': the filename of the music to play (in ''music/'' as .ogg)
** see [[MusicListWML]] for the correct syntax
* '''[volume]''': {{DevFeature1.9}} Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
** '''music''': Changes the music volume.
** '''sound''': Changes the sound volume.
* '''[colour_adjust]''': tints the colour of the screen.
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each colour
* '''[delay]''': pauses the game
** '''time''': the time to pause in milliseconds
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around
** '''x''', '''y''': the location of the unit to overlay on
** '''image''': the image to place on the unit
** {{DevFeature1.9}}: '''[unit_overlay]''' accepts a [[StandardUnitFilter]] as argument
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit
** '''x''', '''y''': the location of the unit to remove an overlay from
** '''image''': the image to remove from the unit
** {{DevFeature1.9}}: '''[remove_unit_overlay]''' accepts a [[StandardUnitFilter]] as argument
* '''[animate_unit]''': Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
** '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
** '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
** '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
** '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
** '''hits''': yes/no: which according variation of a attack/defense animation shall be chosen (required)
** '''text''': a text to hover during the animation
** '''red''': red value for the text color (0-255)
** '''green''': green value for the text color
** '''blue''': blue value for the text color
** '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
** '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
** '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated
* '''[label]''' places a label on the map.
** '''x''', '''y''': the location of the label
** '''text''': what the label should say
** '''team_name''': if specified, the label will only be visible to the given team.
** '''colour''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
** '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
** '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
** '''immutable''': whether this label is protected from being removed or changed by players. Default yes. {{DevFeature1.9}}
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
** '''message''': the message to show.
* '''[wml_message]''' outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
** '''message''': the message to show.
** '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.
* '''[open_help]''' opens the in-game help.
** '''topic''': the id of the topic to open
* '''[show_objectives]''': {{DevFeature}} refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
** '''side''': the side to show the objectives. If not set, all sides are used.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor like screenshake and plays <soundfile>. ('''{TREMOR}''' is a deprecated version, equivalent to '''{QUAKE (rumble.ogg)}''')
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

LuaWML

2010-08-05T04:44:38Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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. The table also provides the fields '''x1''', '''y1''', '''x2''', and '''y2''', containing map locations, and the sub-tables '''weapon''' and '''second_weapon''' containing attacks, if relevant for the current event.

== 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 args = ...
if target_hex.is_set and
(args.x1 ~= target_hex.x or args.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 args = ...

loads the parameter of the script into the ''args'' local variable. Since it is a ''moveto'' event, the ''args'' 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
(args.x1 ~= target_hex.x or args.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
(args.x1 ~= wesnoth.get_variable("target_hex.x") or args.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.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

== 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. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { { "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]
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

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", { { "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

LuaWML/Units

2010-08-05T04:43:35Z

Silene: Added unit modifiers

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''hitpoints''': integer (read/write) {{DevFeature1.9}}
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write) {{DevFeature1.9}}
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields) {{DevFeature1.9}}
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists.

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

{{DevFeature1.9}}

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

{{DevFeature1.9}}

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

{{DevFeature1.9}}

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

{{DevFeature1.9}}

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

{{DevFeature1.9}}

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

{{DevFeature1.9}}

Modifies a given unit. The second argument is the type of the modification (either trait, object, or advance). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.get_unit_type_ids ====

Returns an array containing all the unit type IDs the engine knows about.

local unit_types = wesnoth.get_unit_type_ids()
wesnoth.message(string.format("%d unit types registered. First one is %s.", #unit_types, unit_types[1]))

==== wesnoth.get_unit_type ====

Returns the unit type with the corresponding ID.

local lich_cost = wesnoth.get_unit_type("Ancient Lich").cost

Unit types are proxy tables with the following fields:
* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

==== wesnoth.unit_types ====

{{DevFeature1.9}}

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

local function display_stats(n, t)
wesnoth.message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

LuaWML

2010-08-03T19:23:45Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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. The table also provides the fields '''x1''', '''y1''', '''x2''', and '''y2''', containing map locations, and the sub-tables '''weapon''' and '''second_weapon''' containing attacks, if relevant for the current event.

== 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 args = ...
if target_hex.is_set and
(args.x1 ~= target_hex.x or args.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 args = ...

loads the parameter of the script into the ''args'' local variable. Since it is a ''moveto'' event, the ''args'' 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
(args.x1 ~= target_hex.x or args.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
(args.x1 ~= wesnoth.get_variable("target_hex.x") or args.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.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.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.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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

== 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. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { { "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]
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

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", { { "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

LuaWML/Tiles

2010-08-03T19:22:41Z

Silene: Added location matching

This page describes the [[LuaWML]] functions for handling terrains and tiles.

==== wesnoth.get_map_size ====

Returns the width, the height, and the border size of the map.

local w,h,b = wesnoth.get_map_size()

==== wesnoth.get_terrain ====

Returns the terrain code for the given location.

local is_grassland = wesnoth.get_terrain(12, 15) == "Gg"

==== wesnoth.set_terrain ====

Modifies the terrain at the given location.

function create_village(x, y)
wesnoth.set_terrain(x, y, "Gg^Vh")
end

==== wesnoth.get_terrain_info ====

Returns the terrain details for the given terrain code.

local is_keep = wesnoth.get_terrain_info(wesnoth.get_terrain(12, 15)).keep

Terrain info is a plain table with the following fields:
* '''id''': string
* '''name''', '''description''': translatable strings
* '''castle''', '''keep''', '''village''': booleans
* '''healing''': integer

==== wesnoth.get_selected_tile ====

Returns the two coordinates of the currently selected tile. This is mostly useful for defining command-mode helpers.

function chg_unit(attr, val)
local x, y = wesnoth.get_selected_tile()
if not x then wesnoth.message("Error", "No unit selected."); return end
helper.modify_unit({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)

==== wesnoth.get_locations ====

{{DevFeature1.9}}

Returns a table containing all the locations matching the given filter. Locations are stored as pairs: tables of two elements.

-- replace all grass terrains by roads
for i,loc in ipairs(wesnoth.get_locations { terrain = "Gg" }) do
wesnoth.set_terrain(loc[1], loc[2], "Rr")
end

==== wesnoth.match_location ====

{{DevFeature1.9}}

Returns true if the given location passes the filter.

bool b = wesnoth.match_location(x, y, { terrain = "Ww", { "filter_adjacent_location", terrain = "Ds,*^Bw*" } })

LuaWML/Display

2010-08-01T08:28:36Z

Silene: Mentioned synchronization

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

Pops some text above a map tile.

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

==== 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 a '''[grid]''' child.

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

==== 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" })

LuaWML

2010-08-01T08:27:34Z

Silene: Added missing link

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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. The table also provides the fields '''x1''', '''y1''', '''x2''', and '''y2''', containing map locations, and the sub-tables '''weapon''' and '''second_weapon''' containing attacks, if relevant for the current event.

== 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 args = ...
if target_hex.is_set and
(args.x1 ~= target_hex.x or args.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 args = ...

loads the parameter of the script into the ''args'' local variable. Since it is a ''moveto'' event, the ''args'' 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
(args.x1 ~= target_hex.x or args.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
(args.x1 ~= wesnoth.get_variable("target_hex.x") or args.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.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.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.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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

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

== 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. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { { "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]
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

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", { { "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

LuaWML/Misc

2010-08-01T08:26:20Z

Silene: Added synchronization command

This page describes miscellaneous [[LuaWML]] objects and helpers.

==== wesnoth.game_config ====

Contrarily to the other values of the ''wesnoth'' table, ''game_config'' is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:

* '''version''': string (read only)
* '''base_income''': integer (read/write)
* '''village_income''': integer (read/write)
* '''poison_amount''': integer (read/write)
* '''rest_heal_amount''': integer (read/write)
* '''recall_cost''': integer (read/write)
* '''kill_experience''': integer (read/write)
* '''debug''': boolean (read only)

-- Healing, poison, and regeneration, are a bit weak? Let's boost them!
wesnoth.game_config.poison_amount = 15

==== wesnoth.current ====

As with ''game_config'', ''current'' is a proxy table. Its fields are getter for game-related properties:

* '''side''': integer (read only)
* '''turn''': integer (read only)
* '''event_context''': WML table with attributes ''name'', ''x1'', ''y1'', ''x2'', ''y2'', and children ''weapon'', ''second_weapon'', describing the trigger for the current event.

wesnoth.message(string.format("Turn %d, side %d is playing.", wesnoth.current.turn, wesnoth.current.side))

==== wesnoth.synchronize_choice ====

{{DevFeature1.9}}

Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called.

local result = wesnoth.synchronize_choice(function()
-- called only on the client handling the current side
local choice = 0
wesnoth.show_dialog(some_dialog_cfg, nil, function() choice = wesnoth.get_dialog_value "some_list" end)
return { value = choice }
end)
wesnoth.message(string.format("Selected item: %d", result.value))

==== helper.set_wml_tag_metatable ====

Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.

T = helper.set_wml_tag_metatable {}
W.event { name = "new turn", T.message { speaker = "narrator", message = "?" } }

==== helper.modify_unit ====

Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MODIFY_UNIT] macro.

helper.modify_unit({ id="Delfador" }, { moves=0 })

==== helper.move_unit_fake ====

Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MOVE_UNIT] macro.

helper.move_unit_fake({ id="Delfador" }, 14, 8)

LuaWML

2010-07-29T13:36:12Z

Silene: Added missing links

{{WML Tags}}

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

This tag is a subtag of the '''[event]''' tag. 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]].

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. The table also provides the fields '''x1''', '''y1''', '''x2''', and '''y2''', containing map locations, and the sub-tables '''weapon''' and '''second_weapon''' containing attacks, if relevant for the current event.

== 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 args = ...
if target_hex.is_set and
(args.x1 ~= target_hex.x or args.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 args = ...

loads the parameter of the script into the ''args'' local variable. Since it is a ''moveto'' event, the ''args'' 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
(args.x1 ~= target_hex.x or args.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
(args.x1 ~= wesnoth.get_variable("target_hex.x") or args.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.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[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_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]

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

=== 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.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.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.simulate_combat|wesnoth.simulate_combat]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.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#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]]

=== Lua files ===

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

=== Miscellaneous ===

* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
* [[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]]

== 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. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { { "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]
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

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", { { "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

LuaWML/Display

2010-07-29T13:35:24Z

Silene: Added sound function

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

Pops some text above a map tile.

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

==== 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 a '''[grid]''' child.

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.

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

==== 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" })

LuaWML/Display

2010-07-29T13:29:51Z

Silene: Added canvas setter

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

Pops some text above a map tile.

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

==== 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.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 a '''[grid]''' child.

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.

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

==== 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" })