From The Battle for Wesnoth Wiki
Revision as of 13:28, 3 January 2013 by Elvish Hunter (talk | contribs) (Added wesnoth.get_time_stamp())

This page describes miscellaneous LuaWML objects and helpers.


Contrarily to the other values of the wesnoth table, game_config is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:

  • version: string (read only)
  • base_income: integer (read/write)
  • village_income: integer (read/write)
  • poison_amount: integer (read/write)
  • rest_heal_amount: integer (read/write)
  • recall_cost: integer (read/write)
  • kill_experience: integer (read/write)
  • last_turn: integer (read/write) turn limit, maximum number of turns
  • debug: boolean (read only)
  • mp_debug: boolean (read only) Template:DevFeature1.11
-- Poison a bit weak? Let's boost it!
wesnoth.game_config.poison_amount = 15


As with game_config, current is a proxy table. Its fields are getter for game-related properties:

  • side: integer (read only)
  • turn: integer (read only)
  • event_context: WML table with attributes name, x1, y1, x2, y2, and children weapon, second_weapon, describing the trigger for the current event.
wesnoth.message(string.format("Turn %d, side %d is playing.", wesnoth.current.turn, wesnoth.current.side))


Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called. An optional second function can be passed; if present, it will be used instead of the first one when the client happens to be an AI (hence not enable to interact with a user interface).

local result = wesnoth.synchronize_choice(
    -- Called only on the client handling the current side, if it is a human.
    local choice = 0
      some_dialog_cfg, nil,
        choice = wesnoth.get_dialog_value "some_list"
    return { value = choice }
    -- Called only on the client handling the current side, if it is an AI.
    return { value = math.random(some_list_size) }
wesnoth.message(string.format("Selected item: %d", result.value))


Returns the width and height of an image.

local w, h = wesnoth.get_image_size "units/transport/galleon.png"


Takes two versions strings and an operator, returns whether the comparison yields true. Follows the same rules like the #ifver preprocessor statement.

local function version_is_sufficient(required)
 if not wesnoth.compare_versions then return false end
 return wesnoth.compare_versions(wesnoth.game_config.version, ">=", required)
local required = "1.9.6+svn"
if not version_is_sufficient(required) then wesnoth.message(string.format(
 "Your BfW version is insufficient, please get BfW %s or greater!", required)) end


Template:DevFeature1.11Checks if the file (not necessarily a Lua file) or the directory passed as argument exists. Returns true if the file exists, false otherwise. Follows the same rules like the #ifhave preprocessor statement.

-- Does the user have installed the UMC Music Book 1?
local umc_music = wesnoth.have_file( "~add-ons/UMC_Music_Book_1/_main.cfg" )
-- and if we want to check for the folder?
local music_folder = wesnoth.have_file( "~add-ons/UMC_Music_Book_1/" )


Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string.

wesnoth.set_variable("number", 100)
local vconfig = wesnoth.tovconfig({ key = "$number", another_key = true,
    {"a_subtag", { a_key_in_the_subtag = "foo" }}


Template:DevFeature1.11This function retrieves the current time stamp, that is the amount of milliseconds passed from when the SDL library was initialized. It takes no arguments and returns an integer. WARNING: this function uses the same code as [set_variable] time=stamp, and so it is MP-unsafe. It is provided only for benchmark purposes and AI development, although it should work inside wesnoth.synchronize_choice() as well.

local stamp = wesnoth.get_time_stamp()


Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.

T = helper.set_wml_tag_metatable {}
W.event { name = "new turn", T.message { speaker = "narrator", message = "?" } }


Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the MODIFY_UNIT macro.

helper.modify_unit({ id="Delfador" }, { moves=0 })


Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the MOVE_UNIT macro.

helper.move_unit_fake({ id="Delfador" }, 14, 8)


(A shortcut to set_variable's rand= since math.rand is an OOS magnet and therefore disabled.) Pass a string like you would to set_variable's rand=.

create a random unit at (1, 1) on side=1 :

wesnoth.put_unit(1, 1, { type = helper.rand("Dwarvish Fighter,Dwarvish Thunderer,Dwarvish Scout") })


Template:DevFeature1.11Unlike other languages (Python, Perl, Javascript, ...), Lua does not include a round function. This helper function allows rounding numbers, following the "round half away from zero method", see Wikipedia [[1]]. Returns the number rounded to the nearest integer.

-- this number will be rounded up
helper.round(345.67) -- returns 346
-- this one will be rounded down
helper.round(543.21) -- returns 543
-- an integer stays integer
helper.round(123) -- returns 123
-- works also for negative numbers
helper.round(-369.84) -- returns -370
helper.round(-246.42) -- returns -246