Difference between revisions of "LuaWML/Units"
m (Missing field) |
(Mentioned wesnoth.unit_types) |
||
Line 90: | Line 90: | ||
The metatable of these proxy tables appears as '''"unit type"'''. | The metatable of these proxy tables appears as '''"unit type"'''. | ||
+ | |||
+ | ==== wesnoth.unit_types ==== | ||
+ | |||
+ | {{DevFeature1.9}} | ||
+ | |||
+ | This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]]. | ||
+ | |||
+ | local lich_cost = wesnoth.unit_types["Ancient Lich"].cost | ||
==== wesnoth.simulate_combat ==== | ==== wesnoth.simulate_combat ==== |
Revision as of 17:55, 18 July 2010
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)
- type: 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.
Contents
wesnoth.get_units
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
wesnoth.put_unit
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])
wesnoth.create_unit
Creates a private unit from a WML table.
local u = wesnoth.create_unit { type = "White Mage", gender = "female" }
wesnoth.copy_unit
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)
wesnoth.unit_resistance
Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher 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 = 100 - wesnoth.unit_resistance(u, "fire")
wesnoth.unit_defense
Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)
local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")
wesnoth.unit_movement_cost
Returns the movement cost of a unit on a particular terrain.
local move_cost = wesnoth.unit_movement_cost(u, "Gt")
wesnoth.get_unit_type_ids
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]))
wesnoth.get_unit_type
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".
wesnoth.unit_types
This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by #wesnoth.get_unit_type.
local lich_cost = wesnoth.unit_types["Ancient Lich"].cost
wesnoth.simulate_combat
Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.
local function display_stats(n, t) wesnoth.message(string.format( "Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.", n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp)) end local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def) display_stats("attacker", att_stats) display_stats("defender", def_stats)