LuaAPI/wesnoth/interface

(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

• ♟ wesnoth.interface.delay(milliseconds)

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

wesnoth.delay(500)

wesnoth.interface.deselect_hex

• ♟ wesnoth.interface.deselect_hex()

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

wesnoth.interface.highlight_hex

• ♟ wesnoth.interface.highlight_hex(x, y)

Draws an outline around the specified hex.

wesnoth.interface.select_unit

• ♟ wesnoth.interface.select_unit(x, y, [show_movement, [fire_events]])
• ♟ wesnoth.units.select(unit, [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, wesnoth.units.select 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

• ♟ 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

• ♟ 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

• ♟ 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

• ♟ 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 })
end
-- 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

• ♟ 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

• ♟ 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.lock_view(true)
wesnoth.interface.scroll_to_hex(12, 14, false, true)

wesnoth.interface.is_locked

• ♟ wesnoth.interface.is_locked() → locked?

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

wesnoth.interface.scroll_to_hex

• ♟ 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"
u:scroll_to()

wesnoth.interface.scroll

• ♟ wesnoth.interface.scroll(dx, dy)

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

wesnoth.interface.zoom

• ♟ 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

• ♟ 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

• ♟ 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

• ♟ 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

• ♟ wesnoth.interface.clear_chat_messages()

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

wesnoth.interface.add_item_image

• ♟ wesnoth.interface.add_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.add_item_image(17, 42, "items/orcish-flag.png")

wesnoth.interface.add_item_halo

• ♟ wesnoth.interface.add_item_halo(location, filename)

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

wesnoth.interface.remove_item

• ♟ 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

• ♟ 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.interface.add_hex_overlay

• ♟ wesnoth.interface.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.interface.remove_hex_overlay

• ♟ wesnoth.interface.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

• ♟ 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

• ♟ 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

• ♟ 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.add_overlay_text

(Version 1.17.3 and later only)

• ♟ wesnoth.interface.add_overlay_text(text [, options]) → text handle

Adds a text overlay to the screen that does not move with the map. Pango formatting is supported. The options table supports the following keys:

• size - The font size.
• max_width - Sets the maximum width the text can occupy on the screen, either in screen units (pixels) or as a percentage (a string ending in %). If the text is too long to fit in that width, it will automatically be word-wrapped. Defaults to 100%.
• color - The text color, either as a six-digit hex string (no leading #) or an array of three integers (red, green, and blue).
• bgcolor - If present, a background in this color is placed behind the text to enhance readability. This works like the background behind chat messages, but can be any colour. It is formatted the same as color. If omitted, the background is fully transparent (ie, there is no background).
• bgalpha - If a background colour is specified, this sets its transparency. The default is fully opaque.
• duration - How long the text should be displayed, in milliseconds, or the string 'unlimited' for an infinite duration. Defaults to two seconds.
• fade_time - When the label is removed, either explicitly or because its duration expired, this is the time it takes to fade out, in milliseconds. A value of 0 means the label disappears instantly. Defaults to 100.
• halign - Where to anchor the text horizontally on the screen. Must be one of 'left', 'center', 'right'.
• valign - Where to anchor the text vertically on the screen. Must be one of 'top', 'center', 'bottom'.
• location - The screen offset where the text should be placed, relative to the specified anchor. Defaults to (0,0).

The text handle returned from this function supports the following method calls:

• handle:move(x, y)

Moves the text to a new location on the screen. The provided x and y are offsets from its current location.

• handle:remove([fade_time])

Remove the text from the screen, optionally overriding the fade-out time.

• handle:replace(text, options) → handle

Replaces the text with new text. Options are the same as in add_overlay_text, and the returned handle is the same one.

wesnoth.interface.handle_user_interact

(Version 1.17.6 and later only)

• ♟ wesnoth.interface.handle_user_interact()

Handle user interaction with the game interface. This can be inserted into Lua code that takes a long time to execute in order to prevent the user interface from freezing.

wesnoth.interface.game_display

• ♟ wesnoth.interface.game_display.theme_item ↔ function() → 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."
        })
    end
    return s
end

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.

unit_name

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

unit_type

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

unit_race

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

unit_side

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

unit_level

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

unit_amla

Similar to unit_advancement_options but shows AMLAs only.

unit_traits

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

unit_status

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

unit_alignment

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

unit_abilities

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

unit_hp

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

unit_xp

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

unit_advancement_options

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.

unit_defense

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

unit_vision

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

unit_moves

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

unit_weapons

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:

[element]
  image="melee.png"
  tooltip="...stuff..."
[/element]
[element]
  image="arcane.png"
  tooltip="...stuff..."
[/element]
[element]
  text="6×3 holy sword"
  tooltip="...stuff..."
[/element]
[element]
  # This is empty if the range and type icons both exist.
  text="melee-arcane"
  tooltip="...stuff..."
[/element]
# If the weapon has accuracy or parry...
[element]
  text="+20%/-10%"
  tooltip="Accuracy: +20%
Parry: -10%
"
[/element]
# If the weapon has special abilities...
[element]
  text="magical"
  tooltip="...stuff..."
[/element]

unit_image

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

unit_profile

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

selected_unit

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.

highlighted_unit_weapons

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.

unit_box

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

turn

Shows the current turn count.

gold

Shows the amount of gold for the active side.

villages

Shows the number of villages owned by the active side.

num_units

Shows the number of units owned by the active side.

upkeep

Shows the upkeep and expenses for the active side.

income

Shows the income for the active side

terrain_info

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

terrain

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

[element]
  text="Grassland (Flat)"
[/element]

position

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

zoom_level

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

side_playing

Shows the active side's flag.

observers

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

[element]
  tooltip="Observers
<observer1>
<observer2>
"
  image="misc/eye.png"
[/element]

report_clock

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

[element]
  text="22:32"
[/element]

report_countdown

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

[element]
  text="12:43"
[/element]

Depending on the time limit, the text may also be colored using Pango markup.

If there is no time limit set then it forwards to report_clock.