LuaAPI/plugins

General

A plugin is a Lua script loaded via the command-line option --plugin that runs as a coroutine in parallel with the game UI. Examples of their use in mainline are the host.lua and join.lua scripts which are used during CI to test hosting and joining a game through the multiplayer lobby.

Within the script, data from the game is retrieved via coroutine.yield() which returns three values: events, context, and info:

events, context, info = coroutine.yield()

Events

A table of events the plugin manager has been made aware of, with each event containing the event name in the [1] index and the event data in the [2] index.

Chat

Currently there is only the chat event, which occurs when a chat message or a whisper is sent and contains the following attributes:

• sender - String. The player sending the message.
• message - String. The message being sent.
• whisper - Boolean. Whether the message was sent as a whisper or as a general chat message.

Context

This object contains various functions which can be called to change or set data (mutators). The different contexts available are listed below.

Multiplayer Lobby

context.join

• 🔌 context.join(config)

Joins the currently selected game as a player, moving to the Multiplayer Join context. The config argument should be an empty table.

context.observe

• 🔌 context.observe(config)

Joins the currently selected game as an observer. The config argument should be an empty table.

context.create

• 🔌 context.create(config)

Moves to the game creation screen. The config argument should be an empty table.

context.quit

• 🔌 context.quit(config)

Leaves the lobby. The config argument should be an empty table.

context.chat

• 🔌 context.chat(config)

Sends a public chat message. The config argument must have an attribute message, which will be the text to send as a chat message.

context.select_game

• 🔌 context.select_game(config)

Selects a current game. Must be called before trying to join or observe a game. The config argument must have either the attribute id which which is the ID of the game to select, or the attribute index which is the index of the game to select in the list of games displayed in the lobby (filtering is ignored).

Multiplayer Join

context.launch

• 🔌 context.launch(config)

Joins the game. The config argument provided should be an empty table.

context.quit

• 🔌 context.quit(config)

Returns to the lobby. The config argument provided should be an empty table.

context.chat

• 🔌 context.chat(config)

Sends a public chat message to players who have joined. The config argument provided must have the message attribute, which is the text to be sent as the chat message.

Multiplayer Staging

context.launch

• 🔌 context.launch(config)

Starts the game. The config argument provided should be an empty table.

context.quit

• 🔌 context.quit(config)

Returns to the lobby. The config argument provided should be an empty table.

context.chat

• 🔌 context.chat(config)

Sends a public chat message to players who have joined. The config argument provided must have the message attribute, which is the text to be sent as the chat message.

Game

context.save_game

• 🔌 context.save_game(config)

Triggers a save of the game. The config argument must have an attribute filename, which will be the filename of the resulting save file.

context.save_replay

• 🔌 context.save_replay(config)

Saves a replay of the game. The config argument must have an attribute filename, which will be the filename of the resulting replay file.

context.quit

• 🔌 context.quit(config)

Leaves the currently joined game. The config argument provided should be an empty table.

Dialog

context.skip_dialog

• 🔌 context.skip_dialog(config)

Closes the current modal dialog like the Ok button was clicked. The config argument should be an empty table.

context.quit

• 🔌 context.quit(config)

Does nothing. The config argument should be an empty table.

init

None are available.

Info

This object contains the name attribute which identifies which context the game is currently in, as well as various functions to retrieve data (accessors) based on the current context which are listed below.

Multiplayer Lobby

info.game_list

• 🔌 info.game_list() → config

Returns a config containing the list of games in the lobby and their associated information. This list ignores any filtering.

Multiplayer Join

None are available.

Multiplayer Staging

None are available.

Game

info.scenario_name

• 🔌 info.scenario_name().scenario_name → string

Returns the name of the current scenario. This is the translatable scenario name as shown on the UI during game creation.

titlescreen

• 🔌 info.command_line → config

Returns the command line options provided when starting Wesnoth.

Dialog

None are available.

init

None are available.