LuaAPI/types/unit

A unit proxy encapsulates a reference to a specific unit in the game. The unit could be on the map, on a side's recall list, or private to the Lua engine. A unit proxy may also be invalid, that is, it does not reference any unit.

All unit proxies support the following basic keys. In addition, the units module is treated like a metatable for unit proxies, so any functions defined in that module can be called directly on a unit proxy.

Unit validity

• unit.valid → state

This determines the validity of the unit. If the unit is invalid, it will return nil. In that case, it is not safe to read any other keys from this unit proxy.

If the unit is valid, it will return one of the following strings:

• "map" - The unit is on the map. Its x and y values represent its location.
• "recall" - The unit is on a recall list. Its side value indicates whose recall list. Its x and y values will be used as defaults if put on the map, but otherwise have no meaning.
• "private" - The unit is private to Lua.

Some operations may not work on specific types of units. This will be noted wherever relevant.

Unit location

• unit.x ↔ x coordinate
• unit.y ↔ y coordinate
• unit.loc → x, y
• unit.loc ← {x, y}

There are multiple ways to get or set the unit's location. Note that setting the location of an on-map unit will _not_ trigger a move or any animations. Note the read/write inconsistency with the unit.loc form:

local u = wesnoth.units.get "hero"
local x,y = u.loc
-- Move the unit three spaces right and two spaces down:
u.loc = {x = x + 3, y = y + 2}

This is done for backwards compatibility, as this form was read-only for a long time. Also note that assigning it accepts either an array of two values or a table with x and y keys.

Unit identity

• unit.id → id
• (private or recall only) unit.id ← id

The unit ID is read-only for on-map units, as changing it would cause consistency problems in the game map, but it can be changed for recall list or private units.

• unit.side ↔ side_number

The index of the side the unit belongs to

• unit.type → unit type ID
• unit.variation → variation ID

The string of the unit type or variation. This can be used to look up the unit type object in wesnoth.unit_types:

local u = wesnoth.units.get "hero"
local ut = wesnoth.unit_types[u.type].variations[u.variation]

• unit.gender → gender

The unit's gender - one of the strings "male" or "female".

• unit.race → race ID

The unit's race, a string which can be used to look up the racial information in wesnoth.races.

Unit appearance

• unit.portrait ↔ profile picture
• unit.image_mods → image mods string
• unit.ellipse ↔ ellipse path
• unit.halo ↔ halo path
• unit.hidden ↔ hidden?
• unit.name ↔ name
• unit.description ↔ description
• unit.facing ↔ direction
• unit.overlays → list of overlays

Unit stats

• unit.hitpoints ↔ current hp
• unit.max_hitpoints ↔ max hp

The unit's current and maximum hit points.

• unit.experience ↔ current xp
• unit.max_experience ↔ max xp

The unit's current and maximum experience points.

• unit.moves ↔ current mp
• unit.max_moves ↔ max mp

The unit's current and maximum movement points.

• unit.attacks_left ↔ attacks left this turn
• unit.max_attacks ↔ max attacks per turn

The unit's current and maximum attacks this turn.

• unit.level ↔ level

The unit's level, which determines the experience gained from fighting or killing it.

• unit.recall_cost ↔ cost to recall the unit

The gold cost to recall this unit.

• unit.cost → cost to recruit the unit

The gold that was spent to recruit this unit (if it was recruited) or that would have been spent.

• unit.canrecruit ↔ is leader?

Whether the unit is a leader and can recruit.

• unit.zoc ↔ emits zoc?

Whether the unit has a zone of control.

• unit.alignment ↔ alignment string

The unit's alignment, determining its time of day bonuses. One of the strings "liminal", "lawful", "chaotic", or "neutral".

• unit.upkeep ↔ upkeep

The unit's upkeep. Can be an integer, the string "full" indicating its upkeep is equal to its level, or the string "loyal". For writing, the string "free" is considered synonymous to "loyal".

Misc writable keys

• unit.goto → x, y
• unit.goto ← {x, y}

The location the unit will move towards at the beginning of each turn. Like loc, the inconsistency between read and write is for backwards compatibility.

• unit.usage ↔ usage string

The unit's usage string, used by the AI mainly for recruiting purposes. Thus changing this is unlikely to do anything much.

• unit.renamable ↔ can rename?

Whether the player is allowed to rename this unit.

• unit.undead_variation ↔ variation ID

The variation ID that the unit will become when killed by a plague attack.

• unit.role ↔ role string

The unit's role. This value isn't used anywhere by the engine, but can be filtered on.

• unit.resting ↔ is resting?

Whether the unit is currently resting. Resting units gain 2 HP at the beginning of the next turn.

• unit.recall_filter ↔ filter config

For leader units, this is the filter determining which units they are permitted to recall.

• unit.extra_recruit ↔ list of recruits

A list of extra unit types that this leader can recruit.

• unit.advances_to ↔ list of advancements

A list of unit types that this unit can advance to.

• unit.advancements ↔ list of AMLA configs

A list of modification configs that this unit can choose on advancement.

Unit sub-tables

• unit.status.status ↔ status active?

Unit statuses are arbitrary boolean flags stored with the unit that can be filtered on.

• unit.variables[path] ↔ variable value
• unit.variables.__cfg ↔ all unit variables

This is a variables table with the same semantics as wml.variables. If arrays are needed, it (or the unit it belongs to) can be passed as the second parameter to wml.array_access.get or wml.array_access.set.

• unit.attacks → list of weapons
• unit.attacks.attack_name ↔ weapon proxy
• unit.attacks[index] ↔ weapon proxy
• #unit.attacks → number of weapons

A list of the unit's weapons. Though it is not assignable, the list is modifiable. Attacks can be looked up by index or by name. An attack can be replaced wholesale, or appended by indexing at the list's length and assigning. Attacks can be deleted by assigning nil to an index. If a string key is assigned, the attack being assigned is updated to use that key as its name. The attacks table can be iterated either with ipairs or pairs, with the latter covering the attacks by their name but still in order.

For information on what can be done with the weapon proxy itself, see here.

Other unit attributes

• unit.traits → list of trait IDs

A list of the traits the unit possesses. This is only the trait IDs, not their full definitions.

• unit.abilities → list of ability IDs

A list of the abilities the unit possesses. This is only the ability IDs, not their full definitions.

• unit.animations → list of animation IDs

A list of the animations the unit possesses. This is only the animation flags, not their full definitions.

• unit.__cfg → config dump of the unit

A full config dump of the unit. This can be used to modify keys that are not otherwise supported.