ui.lua

This script contains UI related functions like for moving the mouse or the view or clicking on fields and UI elements.

Note

Do not use any of these functions for multiplayer scenarios or winconditions, because a game will likely desync then.

To make these functions available include this file at the beginning of a script via:

include "scripting/ui.lua"

scroll_to_map_pixel(map_pixel[, return_immediate = false])

Changed in version 1.2.1: Added parameter return_immediate.

Make a nice moving transition to center on the ‘map_pixel’, which is a table that must contain ‘x’ and ‘y’ keys. The function will return as soon as the transition is completed. Usually this function is useful when scrolling back after using scroll_to_field() or wait_for_roadbuilding_and_scroll(). The return value of these functions can be passed to scroll_to_map_pixel to move back to the previous location.

Parameters

• map_pixel (table) – pixels to focus on.

• return_immediate (boolean) – Whether to return from the function call immediately, even if the transition is still ongoing.

Example:

include "scripting/ui.lua"
include "scripting/messages.lua"

local rocks_field = wl.Game().map:get_field(12, 34)

-- scroll to 'rocks_field'; 'prior_location' will be the position from where we are scrolling from
local prior_location = scroll_to_field(rocks_field)
campaign_message_box({title= "New observation",
                      body = "We have found some rocks!",
                      position = "top"})
-- after clicking 'OK' scroll back
scroll_to_map_pixel(prior_location)

scroll_to_field(field[, return_immediate = false])

Changed in version 1.2.1: Added parameter return_immediate.

Make a nice moving transition to center the ‘field’ on screen. The function will return as soon as the transition is completed.

Parameters

• field (wl.map.Field) – Field to center the view on

• return_immediate (boolean) – Whether to return from the function call immediately, even if the transition is still ongoing.

Returns

the prior center map pixel of the MapView as a table containing ‘x’ and ‘y’ keys.

mouse_to_pixel(x, y[, return_immediate = false])

Changed in version 1.2.1: Added parameter return_immediate.

Make a nice moving transition for the mouse to the given pixels relative to the top left corner of the screen. The function will return as soon as the transition is completed.

Parameters

• x (integer) – x position to move the mouse to

• y (integer) – y position to move the mouse to

• return_immediate (boolean) – Whether to return from the function call immediately, even if the transition is still ongoing.

mouse_to_field(field[, return_immediate = false])

Changed in version 1.2.1: Added parameter return_immediate.

Move the mouse on the given field. Makes sure that the field is inside the current view area by scrolling the view if necessary. The function will return as soon as the transition is completed.

Parameters

• field (wl.map.Field) – Field to mouse to

• return_immediate (boolean) – Whether to return from the function call immediately, even if the transition is still ongoing.

mouse_to_panel(panel[, return_immediate = false])

Changed in version 1.2.1: Added parameter return_immediate.

Move the mouse to the center of the given ui element. The function will return as soon as the transition is completed.

Parameters

• panel (wl.ui.Panel) – Panel to mouse to

• return_immediate (boolean) – Whether to return from the function call immediately, even if the transition is still ongoing.

click_building(player, building_name)

Click on the first building of type ‘building_name’ owned by ‘player’.

Parameters

• player (wl.game.Player) – Player to search building for.

• building_name (string) – Building name to look for.

Returns

true if a building was clicked

click_button(name)

Searches through all open windows for a button named ‘name’ and, if found, clicks it.

This function is used only by the testsuite.

Parameters

name (string) – Name of the button to click.

Returns

true if a button was clicked

close_windows()

Closes all open windows.

wait_for_roadbuilding()

Sleeps while player is in roadbuilding mode.

wait_for_roadbuilding_and_scroll(field)

Sleeps while player is in roadbuilding mode, then calls scroll_to_field(field).

Parameters

field (wl.map.Field) – Field to scroll to

Returns

The return value of scroll_to_field.