LuaWML/Units

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)
• name: translatable string (read only)
• hitpoints, max_hitpoints, experience, max_experience, max_moves: integers (read only)
• moves: integer (read/write)
• resting: boolean (read/write)
• petrified, canrecruit: booleans (read only)
• role, facing: strings (read/write)
• __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 private to the Lua code (#wesnoth.create_unit, #wesnoth.copy_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, 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.

wesnoth.get_units

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

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

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, 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.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)

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