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)
• type: 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.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

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)