LuaAPI/types/unit

From The Battle for Wesnoth Wiki
< LuaAPI‎ | types

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

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.xx coordinate
  • unit.yy coordinate
  • unit.locx, 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.idid
  • (private or recall only) unit.idid

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

The index of the side the unit belongs to

  • unit.typeunit type ID
  • unit.variationvariation 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.gendergender

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

  • unit.racerace ID

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

Unit appearance

  • unit.portraitprofile picture
  • unit.image_modsimage mods string
  • unit.ellipseellipse path
  • unit.halohalo path
  • unit.hiddenhidden?
  • unit.namename
  • unit.descriptiondescription
  • unit.facingdirection
  • unit.overlayslist of overlays

Unit stats

  • unit.hitpointscurrent hp
  • unit.max_hitpointsmax hp

The unit's current and maximum hit points.

  • unit.experiencecurrent xp
  • unit.max_experiencemax xp

The unit's current and maximum experience points.

  • unit.movescurrent mp
  • unit.max_movesmax mp

The unit's current and maximum movement points.

  • unit.attacks_leftattacks left this turn
  • unit.max_attacksmax attacks per turn

The unit's current and maximum attacks this turn.

  • unit.levellevel

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

  • unit.recall_costcost to recall the unit

The gold cost to recall this unit.

  • unit.costcost to recruit the unit

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

  • unit.canrecruitis leader?

Whether the unit is a leader and can recruit.

  • unit.zocemits zoc?

Whether the unit has a zone of control.

  • unit.alignmentalignment string

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

  • unit.upkeepupkeep

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.gotox, 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.usageusage string

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

  • unit.renamablecan rename?

Whether the player is allowed to rename this unit.

  • unit.undead_variationvariation ID

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

  • unit.rolerole string

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

  • unit.restingis resting?

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

  • unit.recall_filterfilter config

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

  • unit.extra_recruitlist of recruits

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

  • unit.advances_tolist of advancements

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

  • unit.advancementslist of AMLA configs

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

Unit sub-tables

  • unit.status.statusstatus active?

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

  • unit.variables[path] ↔ variable value
  • unit.variables.__cfgall 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.attackslist of weapons
  • unit.attacks.attack_nameweapon proxy
  • unit.attacks[index] ↔ weapon proxy
  • #unit.attacksnumber 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.traitslist of trait IDs

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

  • unit.abilitieslist of ability IDs

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

  • unit.animationslist of animation IDs

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

  • unit.__cfgconfig dump of the unit

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

This page was last edited on 24 January 2023, at 06:52.