messages.lua

Functions to send messages to the player and to add objectives to campaigns.

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

include "scripting/messages.lua"

send_to_inbox(player, title, body, parameters)

Sends a message to the inbox of a player. If the popup parameter is true and the player is in roadbuilding mode, the message is sent after the player leaves the roadbuilding mode (only in singleplayer)

Parameters

• player (wl.game.Player) – the recipient of the message

• title (string) – the localized title of the message

• body (string) – the localized body of the message. You can use rt functions here.

• parameters (table) – Array of message parameters as defined in the Lua interface, for wl.game.Player.send_to_inbox(), e.g. {field=f,popup=true}. The popup parameter must be set.

send_to_all_inboxes(text[, heading])

Sends a message to the inbox of all players and show it instantly. This is mainly used for winconditions to show the status.

Parameters

• text (string) – the localized body of the message. You can use richtext functions here. E.g. p(_("text")).

• heading (string) – the localized title of the message (optional)

message_box(player, title, message, parameters)

Waits if player is in building mode, then shows a scenario message box. Usually you want to use campaign_message_box() which has more options, e.g. positioning of message boxes.

Parameters

• player (wl.game.Player) – the recipient of the message

• title (string) – the localized title of the message

• message (string) – the localized body of the message. You must use richtext functions here, e.g. p(_("message"))

• parameters (array) – Array of message parameters as defined in the Lua interface, for wl.game.Player.message_box(), e.g. {field=f}.

campaign_message_box({message, [opts]}, [sleeptime])

Pause a game and show a message box for player 1. Since this function can have several options there is an example below this description.

Parameters

• [opts] (table message,) –

  The message consist of the title, the body and optional parameters. Note that the body must be formatted using the richtext functions, e.g. p(_("message"))

  [opts] can be a separated list of key value pairs defined by wl.game.Player.message_box() and the following ones:

  position - A string that indicates at which border of the screen the message box shall appear. Can be “top”, “bottom”, “right”, “left” or a combination (e.g. “topright”). Overrides posx and posy. Default: Center. If only one direction is indicated, the other one stays centered.

  scroll_back - If true, the view scrolls/jumps back to where it came from. If false, the new location stays on the screen when the message box is closed. Default: False.

  show_instantly - If true, the message box is shown immediately. If false, this function will wait until the player leaves the roadbuilding mode. Be aware that this can be very interruptive. Default: :type false:.

  allow_next_scenario - If set to true, show a button that allows starting

  the next scenario at once. Defaults to false.

• sleeptime (int) – ms spent sleeping after the message has been dismissed by the player

Example:

local scroll_to_field = map:get_field(47, 10)
campaign_message_box({title = "The title",     -- title of the window
                      body = p("The body"),    -- text inside the window
                      w = 200,                 -- width (wl.game.Player.message_box())
                      h = 150,                 -- height (wl.game.Player.message_box())
                      position = "topleft",
                      field = scroll_to_field, -- see wl.game.Player.message_box()
                      scroll_back = true       -- only useful if 'field' was set
                     },
                     200                      -- optional sleeptime
                    )

In the campaigns of this game the table of message is defined in a separate file called texts.lua.

messagebox_h_step(steps)

Helper function to get a height for a messagebox that is changed relative to the default in a way that can still follow the scaling of themes.

Parameters

steps (signed int) – The number of steps by which to increase or decrease the height

messagebox_w_step(steps)

Helper function to get a width for a messagebox that is changed relative to the default in a way that can still follow the scaling of themes.

Parameters

steps (signed int) – The number of steps by which to increase or decrease the width

add_campaign_objective(objective)

Adds an objective to a campaign.

Parameters

objective (wl.game.Objective) – The objective to be added. If the variable name exists, obj_name, obj_title and obj_body are used. Otherwise, it needs to have a name, title, and body.

Returns

The new objective.

new_objectives(...)

Append an objective text with a header to a dialog box in a nice fashion. For displaying objectives with an extra title when an advisor is talking

Provides nice formatting for objective texts. The following arguments will be parsed:

• number: the number of objectives described in the body

• body: the objective text, e.g. created with objective_text()

Returns

a rich text object that contains the formatted objective text & title.

campaign_message_with_objective(message, objective[, sleeptime])

Sets message.h and message.w if not set and calls message_box(player, title, body, parameters) for player 1.

Adds an objective to the scenario afterwards.

Parameters

• message (string) – the message to be sent

• objective (wl.game.Objective) – The objective to be added. If the variable obj_name exists, obj_name, obj_title and obj_body are used. Otherwise, it needs to have a name, title, and body.

• sleeptime (int) – ms spent sleeping after the message has been dismissed by the player

Returns

The new objective.

set_objective_done(objective[, sleeptime])

Sets an objectve as done and sleeps for a bit.

Parameters

• objective (wl.game.Objective) – The objective to be marked as done.

• sleeptime (int) – The milliseconds to sleep. Defaults to 3000.