From The Battle for Wesnoth Wiki
< LuaWML
Revision as of 08:12, 16 March 2010 by Silene (talk | contribs) (Split LuaWML page)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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.


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


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


Creates a private unit from a WML table.

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


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)


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


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