Difference between revisions of "LuaAPI/plugins"

From The Battle for Wesnoth Wiki
(titlescreen)
 
(3 intermediate revisions by the same user not shown)
Line 25: Line 25:
 
==== Multiplayer Lobby ====
 
==== Multiplayer Lobby ====
 
===== context.join =====
 
===== context.join =====
* {{LuaPluginOnly}} '''context.join'''(''config'')
+
* {{LuaPluginOnly}} ''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.
 
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 =====
* {{LuaPluginOnly}} '''context.observe'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''observe'''(''config'')
  
 
Joins the currently selected game as an observer. The ''config'' argument should be an empty table.
 
Joins the currently selected game as an observer. The ''config'' argument should be an empty table.
  
 
===== context.create =====
 
===== context.create =====
* {{LuaPluginOnly}} '''context.create'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''create'''(''config'')
  
 
Moves to the game creation screen. The ''config'' argument should be an empty table.
 
Moves to the game creation screen. The ''config'' argument should be an empty table.
  
 
===== context.quit =====
 
===== context.quit =====
* {{LuaPluginOnly}} '''context.quit'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''quit'''(''config'')
  
 
Leaves the lobby. The ''config'' argument should be an empty table.
 
Leaves the lobby. The ''config'' argument should be an empty table.
  
 
===== context.chat =====
 
===== context.chat =====
* {{LuaPluginOnly}} '''context.chat'''(''config'')
+
* {{LuaPluginOnly}} ''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.
 
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 =====
* {{LuaPluginOnly}} '''context.select_game'''(''config'')
+
* {{LuaPluginOnly}} ''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).
 
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).
  
 
===== info.game_list =====
 
===== info.game_list =====
* {{LuaPluginOnly}} '''info.game_list'''() → config
+
* {{LuaPluginOnly}} ''info''.'''game_list'''() → config
  
 
Returns a config containing the list of games in the lobby and their associated information. This list ignores any filtering.
 
Returns a config containing the list of games in the lobby and their associated information. This list ignores any filtering.
Line 61: Line 61:
 
==== Multiplayer Join ====
 
==== Multiplayer Join ====
 
===== context.launch =====
 
===== context.launch =====
* {{LuaPluginOnly}} '''context.launch'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''launch'''(''config'')
  
 
Joins the game. The ''config'' argument provided should be an empty table.
 
Joins the game. The ''config'' argument provided should be an empty table.
  
 
===== context.quit =====
 
===== context.quit =====
* {{LuaPluginOnly}} '''context.quit'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''quit'''(''config'')
  
 
Returns to the lobby. The ''config'' argument provided should be an empty table.
 
Returns to the lobby. The ''config'' argument provided should be an empty table.
  
 
===== context.chat =====
 
===== context.chat =====
* {{LuaPluginOnly}} '''context.chat'''(''config'')
+
* {{LuaPluginOnly}} ''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.
 
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.
Line 77: Line 77:
 
==== Multiplayer Staging ====
 
==== Multiplayer Staging ====
 
===== context.launch =====
 
===== context.launch =====
* {{LuaPluginOnly}} '''context.launch'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''launch'''(''config'')
  
 
Starts the game. The ''config'' argument provided should be an empty table.
 
Starts the game. The ''config'' argument provided should be an empty table.
  
 
===== context.quit =====
 
===== context.quit =====
* {{LuaPluginOnly}} '''context.quit'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''quit'''(''config'')
  
 
Returns to the lobby. The ''config'' argument provided should be an empty table.
 
Returns to the lobby. The ''config'' argument provided should be an empty table.
  
 
===== context.chat =====
 
===== context.chat =====
* {{LuaPluginOnly}} '''context.chat'''(''config'')
+
* {{LuaPluginOnly}} ''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.
 
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.
Line 93: Line 93:
 
==== Multiplayer Create ====
 
==== Multiplayer Create ====
 
===== context.create =====
 
===== context.create =====
* {{LuaPluginOnly}} '''context.create'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''create'''(''config'')
  
 
The config argument provided should be an empty table.
 
The config argument provided should be an empty table.
Line 100: Line 100:
  
 
===== context.quit =====
 
===== context.quit =====
* {{LuaPluginOnly}} '''context.quit'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''quit'''(''config'')
  
 
The config argument provided should be an empty table.
 
The config argument provided should be an empty table.
Line 107: Line 107:
  
 
===== context.load =====
 
===== context.load =====
* {{LuaPluginOnly}} '''context.load'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''load'''(''config'')
  
 
The config argument provided should be an empty table.
 
The config argument provided should be an empty table.
Line 114: Line 114:
  
 
===== context.update_settings =====
 
===== context.update_settings =====
* {{LuaPluginOnly}} '''context.update_settings'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''update_settings'''(''config'')
  
 
Updates various multiplayer game settings based on which attributes of the below attributes are present:
 
Updates various multiplayer game settings based on which attributes of the below attributes are present:
Line 135: Line 135:
  
 
===== context.set_name =====
 
===== context.set_name =====
* {{LuaPluginOnly}} '''context.set_name'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''set_name'''(''config'')
  
 
The provided config argument must have the '''name''' attribute.
 
The provided config argument must have the '''name''' attribute.
Line 142: Line 142:
  
 
===== context.set_password =====
 
===== context.set_password =====
* {{LuaPluginOnly}} '''context.set_password'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''set_password'''(''config'')
  
 
The provided config argument must have the '''password''' attribute.
 
The provided config argument must have the '''password''' attribute.
Line 149: Line 149:
  
 
===== context.select_level =====
 
===== context.select_level =====
* {{LuaPluginOnly}} '''context.select_level'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''select_level'''(''config'')
  
 
The provided config argument must have the '''index''' attribute.
 
The provided config argument must have the '''index''' attribute.
Line 156: Line 156:
  
 
===== context.select_type =====
 
===== context.select_type =====
* {{LuaPluginOnly}} '''context.select_type'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''select_type'''(''config'')
  
 
The provided config argument must have the '''type''' attribute.
 
The provided config argument must have the '''type''' attribute.
Line 163: Line 163:
  
 
===== context.select_era =====
 
===== context.select_era =====
* {{LuaPluginOnly}} '''context.select_era'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''select_era'''(''config'')
  
 
The provided config argument must have the '''index''' attribute.
 
The provided config argument must have the '''index''' attribute.
Line 170: Line 170:
  
 
===== context.save_game =====
 
===== context.save_game =====
* {{LuaPluginOnly}} '''context.save_game'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''save_game'''(''config'')
  
 
The provided config argument must have the '''index''' attribute.
 
The provided config argument must have the '''index''' attribute.
Line 177: Line 177:
  
 
===== info.get_selected =====
 
===== info.get_selected =====
* {{LuaPluginOnly}} '''info.get_selected'''(''config'')''' → config
+
* {{LuaPluginOnly}} ''info'.'''get_selected'''(''config'')''' → config
  
 
The config argument provided should be an empty table.
 
The config argument provided should be an empty table.
Line 190: Line 190:
  
 
===== info.find_level =====
 
===== info.find_level =====
* {{LuaPluginOnly}} '''info.find_level'''(''config'')''' → config
+
* {{LuaPluginOnly}} ''info''.'''find_level'''(''config'')''' → config
  
 
The config argument provided must contain the '''id''' attribute.
 
The config argument provided must contain the '''id''' attribute.
Line 199: Line 199:
  
 
===== info.find_era =====
 
===== info.find_era =====
* {{LuaPluginOnly}} '''info.find_era'''(''config'')''' → number
+
* {{LuaPluginOnly}} ''info''.'''find_era'''(''config'')''' → number
  
 
The config argument provided must contain the '''id''' attribute.
 
The config argument provided must contain the '''id''' attribute.
Line 206: Line 206:
  
 
===== info.find_mod =====
 
===== info.find_mod =====
* {{LuaPluginOnly}} '''info.find_mod'''(''config'')''' → number
+
* {{LuaPluginOnly}} ''info''.'''find_mod'''(''config'')''' → number
  
 
The config argument provided must contain the '''id''' attribute.
 
The config argument provided must contain the '''id''' attribute.
Line 214: Line 214:
 
==== Game ====
 
==== Game ====
 
===== context.save_game =====
 
===== context.save_game =====
* {{LuaPluginOnly}} '''context.save_game'''(''config'')
+
* {{LuaPluginOnly}} ''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.
 
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 =====
* {{LuaPluginOnly}} '''context.save_replay'''(''config'')
+
* {{LuaPluginOnly}} ''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.
 
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 =====
* {{LuaPluginOnly}} '''context.quit'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''quit'''(''config'')
  
 
Leaves the currently joined game. The ''config'' argument provided should be an empty table.
 
Leaves the currently joined game. The ''config'' argument provided should be an empty table.
  
 
===== info.scenario_name =====
 
===== info.scenario_name =====
* {{LuaPluginOnly}} '''info.scenario_name'''()'''.scenario_name''' → string
+
* {{LuaPluginOnly}} ''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.
 
Returns the name of the current scenario. This is the translatable scenario name as shown on the UI during game creation.
Line 235: Line 235:
 
==== titlescreen ====
 
==== titlescreen ====
 
===== context.play_multiplayer =====
 
===== context.play_multiplayer =====
* {{LuaPluginOnly}} '''context.play_multiplayer'''()
+
* {{LuaPluginOnly}} ''context''.'''play_multiplayer'''()
  
 
Attempts to connect to the multiplayer server.
 
Attempts to connect to the multiplayer server.
 +
 +
===== info.command_line =====
 +
* {{LuaPluginOnly}} ''info''.'''command_line''' → config
 +
 +
Returns the command line options provided when starting Wesnoth.
  
 
==== Dialog ====
 
==== Dialog ====
 
===== context.skip_dialog =====
 
===== context.skip_dialog =====
* {{LuaPluginOnly}} '''context.skip_dialog'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''skip_dialog'''(''config'')
  
 
Closes the current modal dialog like the Ok button was clicked. The ''config'' argument should be an empty table.
 
Closes the current modal dialog like the Ok button was clicked. The ''config'' argument should be an empty table.
  
 
===== context.quit =====
 
===== context.quit =====
* {{LuaPluginOnly}} '''context.quit'''(''config'')
+
* {{LuaPluginOnly}} ''context''.'''quit'''(''config'')
  
 
Does nothing. The ''config'' argument should be an empty table.
 
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 Join ====
 
None are available.
 
 
==== Multiplayer Staging ====
 
None are available.
 
 
==== Multiplayer Create ====
 
 
==== Game ====
 
 
==== titlescreen ====
 
 
==== Dialog ====
 
None are available.
 
  
 
==== init ====
 
==== init ====

Latest revision as of 05:50, 30 September 2022

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 & Info

The context object contains various functions which can be called to change or set data (mutators).

The info 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.

The different contexts and their associated mutator and accessor functions 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).

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

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.

Multiplayer Create

context.create
  • 🔌 context.create(config)

The config argument provided should be an empty table.

Moves to the Multiplayer Staging context using the currently selected content, the same as if the Ok button was clicked.

context.quit
  • 🔌 context.quit(config)

The config argument provided should be an empty table.

Moves to the Multiplayer Lobby context using the currently selected content, the same as if the Cancel button was clicked.

context.load
  • 🔌 context.load(config)

The config argument provided should be an empty table.

Opens the Game Load dialog.

context.update_settings
  • 🔌 context.update_settings(config)

Updates various multiplayer game settings based on which attributes of the below attributes are present:

  • turns
  • gold
  • support
  • experience
  • start_time
  • fog
  • shroud
  • time_limit
  • init_turn_limit
  • turn_bonus
  • reservoir
  • action_bonus
  • observers
  • strict_sync
  • private_replay
  • shuffle_sides
context.set_name
  • 🔌 context.set_name(config)

The provided config argument must have the name attribute.

Sets the name of the game which will be displayed in the lobby.

context.set_password
  • 🔌 context.set_password(config)

The provided config argument must have the password attribute.

Sets the password needed to join the game.

context.select_level
  • 🔌 context.select_level(config)

The provided config argument must have the index attribute.

Selects the content at the specified index. The index is based on the content that is currently visible on the UI based on the name filter.

context.select_type
  • 🔌 context.select_type(config)

The provided config argument must have the type attribute.

Selects the type of content to choose from. The value of type must be one of scenario, user_map, user_scenario, random_map, campaign, sp_campaign. Otherwise the default of scenario will be used.

context.select_era
  • 🔌 context.select_era(config)

The provided config argument must have the index attribute.

Selects the era at the specified index in the list of eras.

context.save_game
  • 🔌 context.save_game(config)

The provided config argument must have the index attribute.

Toggles whether the modification at the specified index is enabled or disabled.

info.get_selected
  • 🔌 info'.'get_selected(config) → config

The config argument provided should be an empty table.

Returns a config containing the following attributes:

  • id: The ID of what is currently selected.
  • name: The user visible, translatable name of what is currently selected.
  • icon: The icon of what is selected. Only populated when it's a campaign.
  • description: The user visible, translatable description of what is selected.
  • allow_era_choice: Whether selecting an era is allowed or not.
  • type: The type of content that is currently selected. Possible values are scenario, user_map, user_scenario, random_map, campaign, sp_campaign.
info.find_level
  • 🔌 info.find_level(config) → config

The config argument provided must contain the id attribute.

Returns a config containing the following attributes:

  • index: The index of the content with the provided ID. If not found, this will be -1.
  • type: The type of content that is currently selected. Possible values are scenario, user_map, user_scenario, random_map, campaign, sp_campaign.
info.find_era
  • 🔌 info.find_era(config) → number

The config argument provided must contain the id attribute.

Returns the index of the era with the provided ID. If not found, this will be -1.

info.find_mod
  • 🔌 info.find_mod(config) → number

The config argument provided must contain the id attribute.

Returns the index of the modification with the provided ID. If not found, this will be -1.

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.

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

context.play_multiplayer
  • 🔌 context.play_multiplayer()

Attempts to connect to the multiplayer server.

info.command_line
  • 🔌 info.command_line → config

Returns the command line options provided when starting Wesnoth.

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.

This page was last edited on 30 September 2022, at 05:50.