LuaAPI/wesnoth/units

The entire units module is only available in the game. It is not available to plugins or map generators.

Functions

wesnoth.units.advance

♟ wesnoth.units.advance(unit, [animate, fire_events])
♟ unit:advance([animate, fire_events])

Advances the unit (and shows the advance unit dialog if needed) if the unit has enough XP. This function should be called after modifying the unit's experience directly. A similar function is called by Wesnoth internally after unit combat. The second argument is a boolean value that specifies whether the advancement should be animated. The third argument is a boolean value that specifies whether advancement related events should be fired.

This function only works for units on the map.

This function can also trigger multiple advancements if the unit has enough XP.

wesnoth.units.clone

♟ wesnoth.units.clone(unit) → copy of unit
♟ unit:clone()

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.units.find_on_map{ type = "Thug" }[1]:clone()
wesnoth.units.erase(u.x, u.y) -- note: not the same as u:erase(), which would be an error
-- u is still valid at this point

wesnoth.units.erase

♟ wesnoth.units.erase(unit)
♟ wesnoth.units.erase(x, y)
♟ unit:erase()

Erases a unit from the map. After calling this on a unit, the unit is no longer valid. Does not work on private units - this usage will raise an error.

wesnoth.units.extract

♟ wesnoth.units.extract(unit)
♟ unit:extract()

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 list = {}
for i,u in ipairs(wesnoth.units.find_on_recall{ side = 1 }) do
    u:extract()
    table.insert(list, u.__cfg)
end
wml.array_access.set("player_recall_list", list)

Note: if the unit is on the map, this is just a shortcut for calling #wesnoth.units.clone and then #wesnoth.units.erase. It is, however, the only way to remove a unit from a recall list without putting it on the map.

wesnoth.units.matches

♟ wesnoth.units.matches(unit, filter, [other_unit]) → matched?
♟ wesnoth.units.matches(unit, filter, [location]) → matched?
♟ unit:matches(filter, [other_unit]) → matched?
♟ unit:matches(filter, [location]) → matched?

Returns true if the given unit matches the WML filter passed as the second argument. If other_unit is specified, it is used for the $other_unit auto-stored variable in the filter. Otherwise, this variable is not stored for the filter. If an extra location is specified, the filter matches as if the unit were at that location.

assert(unit.canrecruit == wesnoth.units.matches(unit, { canrecruit = true }))

wesnoth.units.find_attack

♟ wesnoth.units.find_attack(unit, filter) → attack
♟ unit:find_attack(filter) → attack

Returns the first attack that matches the given StandardWeaponFilter.

wesnoth.units.to_map

♟ wesnoth.units.to_map(unit)
♟ wesnoth.units.to_map(unit, x, y)
♟ unit:to_map([x, y])

Places a unit on the map. This unit is described either by a WML table or by a proxy unit (to use the third form, it must be a proxy). Coordinates can be passed as additional arguments; otherwise the table is expected to have two fields x and y, which indicate where the unit will be placed.

-- create a unit with random traits, then erase it
wesnoth.units.to_map({ type = "Elvish Lady" }, 17, 42)
wesnoth.units.erase(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.units.create and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.units.find_on_map({ canrecruit = true })[1]:to_map(1, 1)

If x,y is a village, this function does not capture it (as of 1.14). Use wesnoth.set_village_owner(x, y, unit.side) if that's what you want.

Caution: Using this function will trigger unit placed events. While this may be correct in most cases, there are some cases where it shouldn't, especially if the code is inside the definition of a custom WML tag — it would be an unexpected side-effect from the users point. To work around this, false can be passed additionally as the last argument. This is what is used internally for some tags such as [move_unit], [harm_unit], [unpetrify] or the feeding ability and is not officially part of the API.

wesnoth.units.to_recall

♟ wesnoth.units.to_recall(unit, [side])
♟ unit:to_recall([side])

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit (to use the third form, it must be a proxy). The side of the recall list is given by the second argument if present, or by the side of the unit otherwise.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.units.find_on_map{ x= 17, y = 42 })[1]:to_recall(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.units.create and then putting the resulting unit on a recall list.

wesnoth.units.transform

♟ wesnoth.units.transform(unit, to_type, [to_variation])
♟ unit:transform(to_type, [to_variation])

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.units.find_on_map{x=ev.x1, y=ev.y1}[1]
u:transform("Spearman")
-- If a full heal is desired:
u.hitpoints = u.max_hitpoints
u.status.poisoned = false

wesnoth.units.select

Alias of LuaAPI/wesnoth/interface#wesnoth.interface.select_unit.

wesnoth.units.scroll_to

Alias of LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex.

wesnoth.units.ability

♟ wesnoth.units.ability(unit, ability_tag) → affected
♟ unit:ability(ability_tag) → affected

Returns true if the unit is currently affected 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 u:ability("teleport")
end

wesnoth.units.chance_to_be_hit

♟ wesnoth.units.chance_to_be_hit(unit, terrain_code) → hit chance
♟ unit:chance_to_be_hit(terrain_code) → hit chance

Returns the chance that a unit will be hit on a particular terrain (based on its defence).

wesnoth.units.defense_on

♟ wesnoth.units.defense_on(unit, terrain_code) → defense value
♟ unit:defense_on(terrain_code) → defense value

Returns the defense of a unit on a particular terrain. (Note: it is the actual defense. So the lower it is, the weaker the unit is.)

local flat_defense = u:defense_on("Gt")

wesnoth.unit.resistance_against

♟ wesnoth.units.resistance_against(unit, damage_type, [as_attacker], [x, y]) → resistance value
♟ unit:resistance_against(damage_type, [as_attacker], [x, y]) → resistance value

Returns the resistance of a unit against an attack type. (Note: it is the actual resistance. So the lower 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 = u:resistance_against("fire")

wesnoth.units.jamming_on

♟ wesnoth.units.jamming_on(unit, terrain_code) → cost
♟ unit:jamming_on(terrain_code) → cost

Returns the jamming cost of a unit on a particular terrain.

local jam_cost = u:jamming_on("Gt")

wesnoth.units.movement_on

♟ wesnoth.units.movement_on(unit, terrain_code) → cost
♟ unit:movement_on(terrain_code) → cost

Returns the movement cost of a unit on a particular terrain.

local move_cost = u:movement_on("Gt")

wesnoth.units.vision_on

♟ wesnoth.units.vision_on(unit, terrain_code) → cost
♟ unit:vision_on(terrain_code) → cost

Returns the vision cost of a unit on a particular terrain.

local see_cost = u:vision_on("Gt")

wesnoth.units.add_modification

♟ wesnoth.units.add_modification(unit, type, effects, [write_to_mods])
♟ unit:add_modification(type, effects, [write_to_mods])

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (one of "trait", "object", or "advancement"). The option "advancement" 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. If write_to_mods false, causes it to not write the modification tag to the unit's [modifications] (as would be done with an [object] with no_write=true).

local T = wml.tag
local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
local effects = {
  id = "my_effect_id",
  T.effect { 
    apply_to = "image_mod", 
    replace = "RC(red>blue)" 
  },
  T.effect {
    apply_to = "new_animation",
    T.standing_animation {
      -- AnimationWML
    }
  }
} 
u:add_modification("object", effects)

wesnoth.units.remove_modifications

♟ wesnoth.remove_modifications(unit, filter, [type])
♟ unit:remove_modifications(filter, [type])

Modifies a given unit. The unit needs to be a proxy unit. The second argument is a filter for the modifications to remove. It takes the same syntax as [filter_wml]; all matching modifications will be removed. The third argument is the type (tag name) of the modifications to search for; it defaults to "object", but you can also pass "trait" or "advancement".

local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
u:remove_modifications({ id = "my_effect_id" })

wesnoth.units.create_animator

♟ wesnoth.units.create_animator()

Returns an object that can be used to set up and run an animation. The object has three methods:

animator:run()

Runs the animation. Implicitly clears the animator.

animator:clear()

Clears any units previously added to the animation.

animator:add(unit, flag, hits, params)

Adds a unit to the animation. The flag specifies which animation to play, and the hits parameter is required for attack animations to specify which variant of the animation to play. Possible keys in params are:

facing: A location. The animation will be played with the unit facing that location.
value: Either a number or a list of two numbers. Use this to pass value and/or value_second to default animations that use them.
with_bars: Whether to show HP bars and such while the animation plays.
text: Text to float as the animation plays.
color: Color of the floating text - a list of red, green, blue.
primary: The primary weapon to use for the animation. Must be a Lua unit attack proxy.
secondary: The secondary weapon to use for the animation.

Normal usage is to create it, call add one or more times, then call run.

wesnoth.units.create

♟ wesnoth.units.create(unit_info) → unit

Creates a private unit from a WML table.

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

wesnoth.units.find_on_map

♟ wesnoth.units.find_on_map(filter) → array of units
♟ wesnoth.units.find_on_map(filter, fake_location) → array of units
♟ wesnoth.units.find_on_map(filter, other_unit) → array of 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. If a second unit is passed, it can be referenced via the $other_unit variable in the main filter as well as via the "other" variable in WFL formulas used in the main filter. If a location is passed, the filter is run as if the unit were at that location (rather than its real location). This affects things such as [filter_adjacent] and ability_active, and should work even for a unit on the recall list.

local leaders_on_side_two = wesnoth.units.find_on_map{ side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

wesnoth.units.find_on_recall

♟ wesnoth.units.find_on_recall(filter) → array of units

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

wesnoth.units.find

♟ wesnoth.units.find(filter) → array of units

Returns a list of all units matching the WML filter, both those on the map and those on the recall lists. It is a shorthand for calling both find_on_map and find_on_recall and combining the resulting arrays.

wesnoth.units.get

♟ wesnoth.units.get(x, y) → unit or nil
♟ wesnoth.units.get(id) → unit or nil

Returns the unit at the given location or with the given ID.

local args = ...
local unit = wesnoth.units.get(args.x1, args.y1)

wesnoth.units.get_hovered

Alias of LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit.