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: .. code-block:: lua include "scripting/messages.lua" .. function:: 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) :arg player: the recipient of the message :type player: :class:`wl.game.Player` :arg title: the localized title of the message :type title: :class:`string` :arg body: the localized body of the message. You can use rt functions here. :type body: :class:`string` :arg parameters: Array of message parameters as defined in the Lua interface, for :meth:`wl.game.Player.send_to_inbox`, e.g. ``{field=f,popup=true}``. The popup parameter must be set. :type parameters: :const:`table` .. function:: 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. :arg text: the localized body of the message. You can use :ref:`richtext functions ` here. E.g. ``p(_("text"))``. :type text: :class:`string` :arg heading: the localized title of the message (optional) :type heading: :class:`string` .. function:: message_box(player, title, message, parameters) Waits if player is in building mode, then shows a scenario message box. Usually you want to use :meth:`campaign_message_box` which has more options, e.g. positioning of message boxes. :arg player: the recipient of the message :type player: :class:`wl.game.Player` :arg title: the localized title of the message :type title: :class:`string` :arg message: the localized body of the message. You must use :ref:`richtext functions ` here, e.g. ``p(_("message"))`` :type message: :class:`string` :arg parameters: Array of message parameters as defined in the Lua interface, for :meth:`wl.game.Player.message_box`, e.g. ``{field=f}``. :type parameters: :const:`array` .. function:: 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. :arg table message, [opts]: The message consist of the ``title``, the ``body`` and optional parameters. Note that the ``body`` must be formatted using the :ref:`richtext functions `, e.g. ``p(_("message"))`` **[opts]** can be a separated list of key value pairs defined by :meth:`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``. :arg int sleeptime: ms spent sleeping after the message has been dismissed by the player Example: .. code-block:: lua 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`. .. function:: 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. :arg steps: The number of steps by which to increase or decrease the height :type steps: signed int .. function:: 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. :arg steps: The number of steps by which to increase or decrease the width :type steps: signed int .. function:: add_campaign_objective(objective) Adds an objective to a campaign. :arg objective: The objective to be added. If the variable :attr:`name ` exists, obj_name, obj_title and obj_body are used. Otherwise, it needs to have a name, title, and body. :type objective: :class:`wl.game.Objective` :returns: The new objective. .. function:: 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 :func:`objective_text` :returns: a rich text object that contains the formatted objective text & title. .. function:: 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. :arg message: the message to be sent :type message: :class:`string` :arg 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. :type objective: :class:`wl.game.Objective` :arg sleeptime: ms spent sleeping after the message has been dismissed by the player :type sleeptime: :class:`int` :returns: The new objective. .. function:: set_objective_done(objective[, sleeptime]) Sets an objectve as done and sleeps for a bit. :arg objective: The objective to be marked as done. :type objective: :class:`wl.game.Objective` :arg sleeptime: The milliseconds to sleep. Defaults to 3000. :type sleeptime: :class:`int`