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)
• max_hitpoints, experience, max_experience, max_moves: integers (read only)
• max_attacks: integer (read only)
• attacks_left: integer (read/write) Setting below 0 is limited to 0.
• extra_recruit: table (read/write)
• advances_to: table (read/write)
• hitpoints, experience: integer (read/write)
• moves: integer (read/write)
• resting: boolean (read/write)
• hidden: boolean (read/write)
• petrified, canrecruit: booleans (read only)
• role, facing: strings (read/write)
• status: proxy associative table (read only, read/write fields)
• image_mods: string (read only)
• variables: proxy associative table (read only, read/write fields, including variables.__cfg), only toplevel named fields are proxied
• attacks: (Version 1.13.0 and later only)an object to access the units attacks, you can use the attacks index or the attacks name to index an attack. every attack has the following members:
  • description: translatable string (read/write)
  • name: string (read)
  • type: string (read/write)
  • range: string (read/write)
  • damage: number(read/write)
  • number: number(read/write)
  • movement_used: number(read/write)
  • attack_weight: number(read/write)
  • defense_weight: number(read/write)
  • specials wml table(read/write)
• valid: string or nil (read only)
• __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

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

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

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

wesnoth.put_recall_unit

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

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

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

Returns true if the unit is currently under effect by an ability with this given TAG NAME. This means that the ability could be owned by the unit itself, or by an adjacent unit.

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

wesnoth.unit_types

This is not a function but a table indexed by unit type ids. Its elements are proxy tables with these 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".

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

wesnoth.races

This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about. known fields of each element:

• id: string
• description, name, plural_name (translatable strings)
• num_traits (integer)
• ignore_global_traits (boolean)
• undead_variation (string)

(all read only)

• __cfg: WML table (dump)

wesnoth.message(tostring(wesnoth.races["lizard"].name))

wesnoth.get_traits

Returns a table with named fields (trait id strings) holding the wml tables defining the traits. arguments: none. All global traits the engine knows about, race-specific traits are not included. Known fields and subtags of each element are the ones which were given in the wml definition of the trait.

wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))

wesnoth.simulate_combat

Computes the hitpoint distribution and status chance after a combat between two units. 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.

Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) 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, def_weapon)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

Returns 2 additional tables which contain information about the weapons and the effect of single hits with these keys: num_blows, damage, chance_to_hit, poisons, slows, petrifies, plagues, plague_type, backstabs, rounds, firststrike, drains, drain_constant, drain_percent, attack_num, name. Name is the wml name not the description. If there is no weapon, then name will be nil

local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)
wesnoth.message(string.format(
    "The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",
    att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))

wesnoth.transform_unit

Changes the type of a unit and adjust attributes accordingly. Note that hit points are only changed if necessary to accommodate the new maximum hit points. Poison is automatically removed if the transformed unit is immune.

local ev = wesnoth.current.event_context
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]
wesnoth.transform_unit(u, "Spearman")
-- If a full heal is desired:
u.hitpoints = u.max_hitpoints
u.status.poisoned = false