LuaAPI/wesnoth/interface

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.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.add_item_halo

wesnoth.interface.place_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.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.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.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 turn limit, it may also be colored using Pango markup.