View source for LuaAPI/wesnoth/units

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

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

== Functions ==

=== wesnoth.units.advance ===

* {{LuaGameOnly}} '''wesnoth.units.advance'''(''unit'', [''animate'', ''fire_events''])
* {{LuaGameOnly}} ''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 ===

* {{LuaGameOnly}} '''wesnoth.units.clone'''(''unit'') → ''copy of unit''
* {{LuaGameOnly}} ''unit'':'''clone'''()

Creates a private unit from another unit.

<syntaxhighlight lang='lua'>
-- 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
</syntaxhighlight>

=== wesnoth.units.erase ===

* {{LuaGameOnly}} '''wesnoth.units.erase'''(''unit'')
* {{LuaGameOnly}} '''wesnoth.units.erase'''(''x'', ''y'')
* {{LuaGameOnly}} ''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 ===

* {{LuaGameOnly}} '''wesnoth.units.extract'''(''unit'')
* {{LuaGameOnly}} ''unit'':'''extract'''()

Removes a unit from the map or from a recall list and makes it private.

<syntaxhighlight lang='lua'>
-- 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)
</syntaxhighlight>

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 ===

* {{LuaGameOnly}} '''wesnoth.units.matches'''(''unit'', ''filter'', [''other_unit'']) → ''matched?''
* {{LuaGameOnly}} '''wesnoth.units.matches'''(''unit'', ''filter'', [''location'']) → ''matched?''
* {{LuaGameOnly}} ''unit'':'''matches'''(''filter'', [''other_unit'']) → ''matched?''
* {{LuaGameOnly}} ''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.

<syntaxhighlight lang='lua'>
assert(unit.canrecruit == wesnoth.units.matches(unit, { canrecruit = true }))
</syntaxhighlight>

=== wesnoth.units.find_attack ===

* {{LuaGameOnly}} '''wesnoth.units.find_attack'''(''unit'', ''filter'') &rarr; ''attack''
* {{LuaGameOnly}} ''unit'':'''find_attack'''(''filter'') &rarr; ''attack''

Returns the first attack that matches the given [[StandardWeaponFilter]].

=== wesnoth.units.to_map ===

* {{LuaGameOnly}} '''wesnoth.units.to_map'''(''unit'' [,''fire_event''])
* {{LuaGameOnly}} '''wesnoth.units.to_map'''(''unit'', ''x'', ''y'' [,''fire_event''])
* {{LuaGameOnly}} ''unit'':'''to_map'''([''x'', ''y'' [,''fire_event'']])

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.

<syntaxhighlight lang='lua'>
-- create a unit with random traits, then erase it
wesnoth.units.to_map({ type = "Elvish Lady" }, 17, 42)
wesnoth.units.erase(17, 42)
</syntaxhighlight>

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.

<syntaxhighlight lang='lua'>
-- move the leader back to the top-left corner
wesnoth.units.find_on_map({ canrecruit = true })[1]:to_map(1, 1)
</syntaxhighlight>

If x,y is a village, this function does not capture it (as of 1.14). Use [[LuaWML/Sides#wesnoth.set_village_owner|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 ===

* {{LuaGameOnly}} '''wesnoth.units.to_recall'''(''unit'', [''side''])
* {{LuaGameOnly}} ''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.

<syntaxhighlight lang='lua'>
-- 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)
</syntaxhighlight>

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.rebuild ===

{{DevFeature1.19|4}}

* {{LuaGameOnly}} '''wesnoth.units.rebuild'''(''unit'')
* {{LuaGameOnly}} ''unit'':'''rebuild'''()

Immediately rebuilds the unit from its unit type and modifications, discarding any alterations to non-transient attributes. Does not reset transient attributes such as the units current hitpoints, moves, or experience.

=== wesnoth.units.transform ===

* {{LuaGameOnly}} '''wesnoth.units.transform'''(''unit'', ''to_type'', [''to_variation''])
* {{LuaGameOnly}} ''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.

<syntaxhighlight lang='lua'>
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
</syntaxhighlight>

=== 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 ===

* {{LuaGameOnly}} '''wesnoth.units.ability'''(''unit'', ''ability_tag'') → ''affected''
* {{LuaGameOnly}} ''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.

<syntaxhighlight lang='lua'>
function has_teleport(u)
    return u:ability("teleport")
end
</syntaxhighlight>

=== wesnoth.units.chance_to_be_hit ===

* {{LuaGameOnly}} '''wesnoth.units.chance_to_be_hit'''(''unit'', ''terrain_code'') → ''hit chance''
* {{LuaGameOnly}} ''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 ===

* {{LuaGameOnly}} '''wesnoth.units.defense_on'''(''unit'', ''terrain_code'') → ''defense value''
* {{LuaGameOnly}} ''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.)

<syntaxhighlight lang='lua'>
local flat_defense = u:defense_on("Gt")
</syntaxhighlight>

=== wesnoth.units.resistance_against ===

* {{LuaGameOnly}} '''wesnoth.units.resistance_against'''(''unit'', ''damage_type'', [''as_attacker''], [''x'', ''y'']) → ''resistance value''
* {{LuaGameOnly}} ''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).

<syntaxhighlight lang='lua'>
local fire_resistance = u:resistance_against("fire")
</syntaxhighlight>

=== wesnoth.units.jamming_on ===

* {{LuaGameOnly}} '''wesnoth.units.jamming_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''jamming_on'''(''terrain_code'') → ''cost''

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

<syntaxhighlight lang='lua'>
local jam_cost = u:jamming_on("Gt")
</syntaxhighlight>

=== wesnoth.units.movement_on ===

* {{LuaGameOnly}} '''wesnoth.units.movement_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''movement_on'''(''terrain_code'') → ''cost''

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

<syntaxhighlight lang='lua'>
local move_cost = u:movement_on("Gt")
</syntaxhighlight>

=== wesnoth.units.vision_on ===

* {{LuaGameOnly}} '''wesnoth.units.vision_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''vision_on'''(''terrain_code'') → ''cost''

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

<syntaxhighlight lang='lua'>
local see_cost = u:vision_on("Gt")
</syntaxhighlight>

=== wesnoth.units.add_modification ===

* {{LuaGameOnly}} '''wesnoth.units.add_modification'''(''unit'', ''type'', ''effects'', [''write_to_mods''])
* {{LuaGameOnly}} ''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).

<syntaxhighlight lang='lua'>
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)
</syntaxhighlight>

=== wesnoth.units.remove_modifications ===

* {{LuaGameOnly}} '''wesnoth.remove_modifications'''(''unit'', ''filter'', [''type''])
* {{LuaGameOnly}} ''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 [[FilterWML#Filtering_on_WML_data|[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".

<syntaxhighlight lang='lua'>
local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
u:remove_modifications({ id = "my_effect_id" })
</syntaxhighlight>

=== wesnoth.units.create_animator ===

* {{LuaGameOnly}} '''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 unit should be one that wasn't previously added. The ''flag'' specifies which [[AnimationWML#Common_animation_events_used_by_the_engine|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.

facing is currently not implemented/working.  See https://github.com/wesnoth/wesnoth/issues/9032

* '''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 ===

* {{LuaGameOnly}} '''wesnoth.units.create'''(''unit_info'') → ''unit''

Creates a private unit from a WML table.

<syntaxhighlight lang='lua'>
local u = wesnoth.units.create{ type = "White Mage", gender = "female" }
</syntaxhighlight>

=== wesnoth.units.find_on_map ===

* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'') → ''array of units''
* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'', ''fake_location'') → ''array of units''
* {{LuaGameOnly}} '''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.

<syntaxhighlight lang='lua'>
local leaders_on_side_two = wesnoth.units.find_on_map{ side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name
</syntaxhighlight>

=== wesnoth.units.find_on_recall ===

* {{LuaGameOnly}} '''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 ===

* {{LuaGameOnly}} '''wesnoth.units.find'''(''filter'') → ''array of units''

Returns a list of all [[LuaAPI/types/unit|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 ===

* {{LuaGameOnly}} '''wesnoth.units.get'''(''x'', ''y'') → ''unit or nil''
* {{LuaGameOnly}} '''wesnoth.units.get'''(''id'') → ''unit or nil''

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

<syntaxhighlight lang='lua'>
local args = ...
local unit = wesnoth.units.get(args.x1, args.y1)
</syntaxhighlight>

=== wesnoth.units.get_hovered ===

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

[[Category:Lua Reference]]