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)

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.

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)

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

Returns

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

mouse_to_pixel(x, y)

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

mouse_to_field(field)

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

mouse_to_panel(panel)

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

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.