From The Battle for Wesnoth Wiki


(Version 1.15.0 and later only)

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

Interface functions


  • wesnoth.interface.delay(milliseconds)

Delays the engine for a period of time, specified in milliseconds.



  • wesnoth.interface.deselect_hex()

Reverses any highlight_hex call, leaving all locations unhighlighted. Takes no arguments.


  • wesnoth.interface.highlight_hex(x, y)

Draws an outline around the specified hex.


  • wesnoth.interface.select_unit(x, y, [show_movement, [fire_events]])
  •, [show_movement, [fire_events]])
  • unit:select([show_movement, [fire_events]])

Selects the given unit in the game map as if the player had clicked on it. Argument 3: boolean, whether to show the movement range of any unit on that location (def: true) Argument 4: boolean, whether to fire any select events (def: false).

This function is available under two different names, but the possible arguments are the same in both cases. In other words, can be called with a location instead of a unit, and wesnoth.interface.select_unit can be called with a unit instead of a location.

wesnoth.interface.select_unit(14, 6, true, true)

If called without arguments, this function deselects the current unit from the map as long as the mouse cursor is not on its hex. It will continue to be displayed on the UI sidebar in any case.


  • wesnoth.interface.float_label(x, y, text)

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "<span color='#ff0000'>Ouch</span>")


  • wesnoth.interface.get_displayed_unit() → unit
  • wesnoth.units.get_hovered() → unit

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.interface.get_displayed_unit().name)


  • wesnoth.interface.get_hovered_hex() → x, y

Returns the two coordinates of the currently hovered tile, that is, where the mouse cursor is located. This is mostly useful for defining command-mode helpers.


  • wesnoth.interface.get_selected_hex() → x, y

Returns the two coordinates of the currently selected (highlighted) tile. This is mostly useful for defining command-mode helpers.

function chg_unit(attr, val)
   local x, y = wesnoth.interface.get_selected_hex()
   if not x then wesnoth.message("Error", "No unit selected."); return end
   wesnoth.units.modify({ x = x, y = y }, { [attr] = val })
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
--   :lua chg_unit("status.poisoned", true)


  • wesnoth.interface.get_viewing_side() → side, full_vision

Returns the viewing side of the current client in a multiplayer game.

For a player participating in the game, this will always be the side that they control, or, if they control multiple sides, the one they most recently had control over. However, for an observer client, this will return the currently-active side instead.

The second return value indicates whether the current client has full vision. This can only happen in replays or for observers.

For obvious reasons, use of this function can easily cause out-of-sync errors. Use with care.


  • wesnoth.interface.lock(lock)

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_hex still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

wesnoth.interface.scroll_to_hex(12, 14, false, true)


  • wesnoth.interface.is_locked() → locked?

Returns a boolean indicating whether gamemap view scrolling is currently locked.


  • wesnoth.interface.scroll_to_hex(x, y, [only_if_visible, [instant, [only_if_needed]]])
  • wesnoth.units.scroll_to(unit, [only_if_visible, [instant, [only_if_needed]]])
  • unit:scroll_to([only_if_visible, [instant, [only_if_needed]]])

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen. It is also possible to pass a unit instead of a pair of tile coordinates (regardless of which module the function is called from).

local u = wesnoth.units.get "hero"


  • wesnoth.interface.scroll(dx, dy)

Scrolls the map by the given amount, which may be either positive or negative.


  • wesnoth.interface.zoom(factor, [relative]) → new_zoom

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then wesnoth.zoom(2) sets it to 2, while wesnoth.zoom(2, true) sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call wesnoth.zoom(1, true) to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.


  • wesnoth.interface.skip_messages([skip?])

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.


  • wesnoth.interface.is_skipping_messages()

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.


  • wesnoth.interface.add_chat_message([speaker,] message)

Displays a string in the onscreen chat. The chat line speaker is "Lua" by default, but it can be changed by passing a string before the message.

wesnoth.interface.add_chat_message "Hello World!" -- will result in "<Lua> Hello World!"
wesnoth.interface.add_chat_message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also wml.error for displaying error messages.


  • wesnoth.interface.clear_chat_messages()

Removes all messages from the onscreen chat, including error messages.


  • wesnoth.interface.place_item_image(location, filename)

Places an image at a given location and registers it as a WML [item] would do, so that it can be restored after save/load. Note that the location must be passed as separate x and y coordinates, as in the example.

wesnoth.interface.place_item_image(17, 42, "items/orcish-flag.png")


  • wesnoth.interface.place_item_halo(location, filename)

Behaves the same as #wesnoth.interface.add_item_image but for halos.


  • wesnoth.interface.remove_item(location, [filename])

Removes an overlay set by #wesnoth.interface.add_item_image or #wesnoth.interface.add_item_halo. If no filename is provided, all the overlays on a given tile are removed. Note that the location must be passed as separate x and y coordinates, as in the example.

wesnoth.interface.remove_item(17, 42, "items/orcish-flag.png")


  • wesnoth.interface.get_items(location) → array of item tables

Get all items placed on the specified location. Note that the location must be passed as separate x and y coordinates.


  • wesnoth.add_hex_overlay(location, item_wml)

Places a hex overlay (either an image or a halo) on the given location. The overlay is described by a table supporting the same fields as [item]. This is a lower-level version of the item functions above. Note that the overlay is not kept over save/load cycles.

wesnoth.interface.add_hex_overlay(17, 42, { image = "items/orcish-flag.png" })


  • wesnoth.remove_hex_overlay(location, [filename])

Removes all the overlays at the given location, including any added by wesnoth.interface.add_item_halo or wesnoth.interface.add_item_image (however, such a removal will not be kept over save/load cycles). If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

wesnoth.interface.remove_hex_overlay(17, 42, "items/orcish-flag.png")


  • wesnoth.interface.end_turn([next_side])

Immediately ends the current side's turn. By default, the next sequential side will gain control, but if you pass an argument that side gains control instead.

The next_side can either be a valid side number, or a valid side number plus the total number of sides in the scenario. In the latter case, this function also increases the turn counter by 1.

Using this, it's entirely possible to pass control around without ever increasing the turn counter.


  • wesnoth.interface.allow_end_turn(allow)
  • wesnoth.interface.allow_end_turn(reason)

Enables or disables ending the turn in the UI. You can optionally pass a translatable string to show to the player if they attempt to do so anyway. It will be shown to the player without any additional framing, so it should normally be phrased similar to "You cannot end your turn because...".

To allow the player to end their turn again, just pass true. If you pass false, a default message will be shown.


  • wesnoth.interface.color_adjust(red, green, blue)

Adjust the screen tint. (0,0,0) is no tint, and possible values range from -255 to 255.


  • wesnoth.interface.game_display.theme_itemfunction() → wml table of theme elements

This is an associative table linking item names to functions that describe the content of the in-game user interface. These functions are called with no arguments whenever the user interface is refreshed, and must return a WML table containing [element] children. Each subtag shall contain either a text or an image field that is displayed to the user. It can also contain a tooltip field that is displayed to the user when moused over, and a help field that points to the help section that is displayed when the user clicks on the theme item.

Note that the wesnoth.interface.game_display cannot be iterated using pairs or next to retrieve the items from the current theme. However, built-in items can be recovered as long as their name is known. The example below shows how to modify the unit_status item to display a custom status:

local old_unit_status = wesnoth.interface.game_display.unit_status
function wesnoth.interface.game_display.unit_status()
    local _ = wesnoth.textdomain "mydomain"
    local u = wesnoth.interface.get_displayed_unit()
    if not u then return {} end
    local s = old_unit_status()
    if u.status.entangled then
        table.insert(s, wml.tag.element {
            image = "entangled.png",
            tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
    return s

The things that would need to be to modified in the above code are:

  • the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
  • the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
  • the path to the image ("entangled.png").
  • the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in wesnoth.interface.game_display which will have an effect in the game, together with sample output and a brief description of their use.


Shows the name of the unit the mouse is hovering over.


Shows the type of the unit the mouse is hovering over.


Shows the race of the unit the mouse is hovering over.


Shows the side number and team color of the unit the mouse is hovering over.


Shows the level of the unit the mouse is hovering over.


Similar to unit_advancement_options but shows AMLAs only.


Shows the list of trait names for the unit the mouse is hovering over.


Shows the status icons for statuses afflicting the unit the mouse is hovering over.


Shows the alignment of the unit the mouse is hovering over.


Shows the ability names of the unit the mouse is hovering over.


Shows the current and maximum hit points of the unit the mouse is hovering over.


Shows the current and target experience points of the unit the mouse is hovering over.


Shows the options the unit the mouse is hovering over has for advancement, including both level ups and AMLAs. This item is not used in the default theme.


Shows the defense of the unit the mouse is hovering over.


Shows the current and maximum vision points of the unit the mouse is hovering over.


Shows the current and maximum movement points of the unit the mouse is hovering over.


Shows the available weapons of the unit the mouse is hovering over. The default generator expresses each weapon line (basic details, specials, etc) as a separate element. For example:

  text="6×3 holy sword"
  # This is empty if the range and type icons both exist.
# If the weapon has accuracy or parry...
  tooltip="Accuracy: +20%
Parry: -10%
# If the weapon has special abilities...


Shows the sprite of the unit the mouse is hovering over.


Shows the portrait of the unit the mouse is hovering over.


Nearly every item beginning with unit_ has a corresponding item beginning with selected_unit_, which describes the currently-selected unit (if any) rather than the unit the mouse is hovering over. These items are not used in the default theme.

There is no selected_unit_amla however.


This is almost the same as selected_unit_weapons but with slightly different logic of choosing which unit to show.

tod_stats and selected_tod_stats

Shows the time of day stats for the hex the mouse is hovering over or the hex the selected unit is on. The time of day stats shows the counter of your position in the schedule as well as the entire cycle.

time_of_day and selected_time_of_day

Shows the time of day image for the hex the mouse is hovering over or the hex the selected unit is on.


This is an experimental item that combines a unit display and the time of day.


Shows the current turn count.


Shows the amount of gold for the active side.


Shows the number of villages owned by the active side.


Shows the number of units owned by the active side.


Shows the upkeep and expenses for the active side.


Shows the income for the active side


Shows the icons of the terrain on hex the mouse is hovering over.


Shows the name of the terrain on the hex the mouse is hovering over. For example:

  text="Grassland (Flat)"


Shows the map coordinates of the hex the mouse is hovering over.


Shows the zoom level as a percentage. This item is not used in the default theme.


Shows the active side's flag.


When there is no observer, it returns an empty table. When there are observers, it returns:



This returns the current time in HH:MM format according to the user's preferences, for example:



This returns the current chess-timer countdown in MM:SS format for the player's turn, for example:


Depending on the turn limit, it may also be colored using Pango markup.

This page was last edited on 4 July 2021, at 23:33.