LuaAPI/wesnoth/interface

(Version 1.15.0 and later only)

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

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