The Battle for Wesnoth Wiki - User contributions [en]

Wesnoth:Copyrights

2026-09-04T07:24:51Z

Pentarctagon: /* User Made Content - Code */

This page contains all relevant information regarding copyright and how it applies to different categories of Wesnoth content and code. Should there ever be any contradicting information from other sources concerning Wesnoth and copyright, the information on this page takes precedence.

== The Wiki ==
The content of the Wesnoth wiki is under the [https://www.gnu.org/licenses/fdl.html GNU Free Documentation License (GFDL)]. By contributing content to the wiki, you agree for your contributions to be distributed under the GFDL.

As the project owners, with the right to issue copies of its content under dual or multiple licenses, the Wesnoth maintainers specifically grant the right to copy content from game to wiki or wiki to game, said copy acquiring only the license obligations associated with the destination.

"Content" here refers to any and all text explanations, code snippets and examples, images, and audio files that are part of the wiki.

== The Battle for Wesnoth - Code Contributions ==
Code contributed to the Battle for Wesnoth project is licensed under the [https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html GNU GPL v2] or later. This includes '''all''' code, whether it be C++, lua, WML, or any other language that is currently part of the project or is added in the future. This also includes data files, such as maps, as well as story content.

Some portions of the source code can be used under alternate license terms, whenever stated as such in the source.

== The Battle for Wesnoth - Visual and Audio Contributions ==
All visual and audio assets are licensed under either the GNU GPL v2 or later, or the [https://creativecommons.org/licenses/by-sa/4.0/ Creative Commons BY-SA 4.0]. While existing contributions may be under the GNU GPL v2 or later, all future contributions will be under the CC BY-SA 4.0 license unless they are specifically noted to instead be under the GNU GPL v2 or later. In any case, regardless of whether a visual or audio contribution is licensed under the GNU GPL v2 or later or the CC BY-SA 4.0, the person contributing the asset always retains the full rights to their own work and can continue to use it in whatever way they wish.

Additionally, unless explicitly stated otherwise, all visual and audio assets that are posted to either the [https://forums.wesnoth.org/viewforum.php?f=14 Music & Sound Development forum] or to the [https://forums.wesnoth.org/viewforum.php?f=9 Art Contributions forum] are considered as potential contributions and are automatically placed under either the GNU GPL v2 or later (prior to July 30th, 2017), or the CC BY-SA 4.0 (as of July 30th, 2017).

For visual and audio assets that are licensed under the GNU GPL v2 or later, we interpret "preferred form of the work for making modifications" as the modifiable form that the author chooses to provide us for the source tree.

Visual and audio assets for which you do not own the rights '''cannot''' be accepted, nor can any derivative works, nor anything that falls under [https://en.wikipedia.org/wiki/Fair_use fair use].

== User Made Content - Code ==
Code uploaded to the official Wesnoth add-ons server must be licensed under a version of the GNU GPL or a license that's GPL-compatible. This includes '''all code''', whether it be lua, WML, or any other language that is supported by Wesnoth. This also includes data files, such as maps, as well as story content. If no version of the GNU GPL is specified, all code will by default be placed under the GNU GPL v2 or later.

Code that for any reason cannot be licensed under the GNU GPL is '''not''' allowed on the add-ons server.

== User Made Content - Visual and Audio Content ==
All visual and audio assets must be licensed under either a version of the GNU GPL or [https://en.wikipedia.org/wiki/Creative_Commons_license#Types_of_licenses any Creative Commons license]. This includes "non-Free" variations such as Non-Commercial (NC) and Non-Derivative (ND). If no version of the GNU GPL nor any Creative Commons license is specified, all visual and audio assets will by default be placed under the GNU GPL v2 or later.

For visual and audio assets that are licensed under the GNU GPL, we interpret "preferred form of the work for making modifications" as the modifiable form that the author chooses to upload to the add-ons server.

For visual and audio assets that are not licensed under the GNU GPL, they must be explicitly denoted as released under a Creative Commons license in either:
* a combined toplevel file, e.g. "add-ons/My_Addon/ART_LICENSE"
* a file in the same folder as the asset with ".license" appended, e.g. "add-ons/My_Addon/images/units/axeman.png.license".

Visual and audio assets that for any reason cannot be placed under the GNU GPL or a Creative Commons license are '''not''' allowed on the add-ons server.

MultiplayerServerWML

2026-08-29T15:46:23Z

Pentarctagon: /* Queues */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''registered''': Whether the player is registered (on the forum).
*** '''moderator''': Whether the player is a moderator.
*** '''forum_id''': The forum ID of the player. With '''profile_url_prefix''' this can be used to construct the profile page URL of a player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot or a server-side queue, false otherwise.
** '''queue_type''': Either "normal" or "server_preset".
** '''queue_id''': The ID of the queue this game is being created from.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

When there are enough players to start a game, the last player to join the queue is chosen as the host and their client is told to create the game with the provided settings. This skips the game creation screen and goes straight to the staging screen. The other players in the queue are then told to join that game using the normal [join] command:
* '''[create_game]'''
** '''queue_id''': The ID of the queue to create the game for.
** '''[game]'''
*** '''scenario''': The ID of the scenario to create the game for.
*** '''era''': The ID of the era to use.
*** '''fog''': Whether to have fog enabled.
*** '''shroud''': Whether to have shroud enabled.
*** '''village_gold''': How much gold each village provides.
*** '''village_support''': How much unit support each village provides
*** '''experience_modifier''': The experience modifier to use.
*** '''countdown''': Whether turn timers are enabled.
*** '''countdown_init_time''': The initial timer value in seconds.
*** '''countdown_turn_bonus''': The amount of additional time a player gets each turn
*** '''countdown_reservoir_time''': The granted number of seconds each turn to complete the turn bonus.
*** '''countdown_action_bonus''': Thegranted number of seconds for each unit who have done an action this turn.
*** '''random_start_time''': Whether to start at a random time of day.
*** '''shuffle_sides''': Whether to shuffle the sides' starting positions.
*** '''[options]'''
**** '''[multiplayer]|[era]|[modification]|[campaign]'''
***** '''id''': The id of the content where the option comes from.
***** '''[option]'''
****** '''id''': The name of the variable to store the option's value.
****** '''value''': The option's value.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

MultiplayerServerWML

2026-08-29T15:45:16Z

Pentarctagon: /* Queues */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''registered''': Whether the player is registered (on the forum).
*** '''moderator''': Whether the player is a moderator.
*** '''forum_id''': The forum ID of the player. With '''profile_url_prefix''' this can be used to construct the profile page URL of a player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot or a server-side queue, false otherwise.
** '''queue_type''': Either "normal" or "server_preset".
** '''queue_id''': The ID of the queue this game is being created from.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

When there are enough players to start a game, the last player to join the queue is chosen as the host and their client is told to create the game with the provided settings. This skips the game creation screen and goes straight to the staging screen. The other players in the queue are then told to join that game using the normal [join] command:
* '''[create_game]'''
** '''queue_id''': The ID of the queue to create the game for.
** '''[game]'''
*** '''scenario''': The ID of the scenario to create the game for.
*** '''era''': The ID of the era to use.
*** '''fog''': Whether to have fog enabled.
*** '''shroud''': Whether to have shroud enabled.
*** '''village_gold''': How much gold each village provides.
*** '''village_support''': How much unit support each village provides
*** '''experience_modifier''': The experience modifier to use.
*** '''countdown''': Whether turn timers are enabled.
*** '''countdown_init_time''': The initial timer value in seconds.
*** '''countdown_turn_bonus''': The amount of additional time a player gets each turn
*** '''countdown_reservoir_time''': The granted number of seconds each turn to complete the turn bonus.
*** '''countdown_action_bonus''': Thegranted number of seconds for each unit who have done an action this turn.
*** '''random_start_time''': Whether to start at a random time of day.
*** '''shuffle_sides''': Whether to shuffle the sides' starting positions.
*** '''[options]'''
**** '''[multiplayer]'''
***** '''id''': The id of the content where the option comes from.
***** '''[option]'''
****** '''id''': The name of the variable to store the option's value.
****** '''value''': The option's value.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

MultiplayerServerWML

2026-08-29T15:45:04Z

Pentarctagon: /* Queues */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''registered''': Whether the player is registered (on the forum).
*** '''moderator''': Whether the player is a moderator.
*** '''forum_id''': The forum ID of the player. With '''profile_url_prefix''' this can be used to construct the profile page URL of a player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot or a server-side queue, false otherwise.
** '''queue_type''': Either "normal" or "server_preset".
** '''queue_id''': The ID of the queue this game is being created from.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

When there are enough players to start a game, the last player to join the queue is chosen as the host and their client is told to create the game with the provided settings. This skips the game creation screen and goes straight to the staging screen. The other players in the queue are then told to join that game using the normal [join] command:
* '''[create_game]'''
** '''queue_id''': The ID of the queue to create the game for.
** '''[game]'''
*** '''scenario''': The ID of the scenario to create the game for.
*** '''era''': The ID of the era to use.
*** '''fog''': Whether to have fog enabled.
*** '''shroud''': Whether to have shroud enabled.
*** '''village_gold''': How much gold each village provides.
*** '''village_support''': How much unit support each village provides
*** '''experience_modifier''': The experience modifier to use.
*** '''countdown''': Whether turn timers are enabled.
*** '''countdown_init_time''': The initial timer value in seconds.
*** '''countdown_turn_bonus''': The amount of additional time a player gets each turn
*** '''countdown_reservoir_time''': The granted number of seconds each turn to complete the turn bonus.
*** '''countdown_action_bonus''': Thegranted number of seconds for each unit who have done an action this turn.
*** '''random_start_time''': Whether to start at a random time of day.
*** '''shuffle_sides''': Whether to shuffle the sides' starting positions.
**** '''[options]'''
***** '''[multiplayer]'''
****** '''id''': The id of the content where the option comes from.
****** '''[option]'''
******* '''id''': The name of the variable to store the option's value.
******* '''value''': The option's value.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

Release Steps

2026-08-20T22:30:49Z

Pentarctagon: /* Release (stable and master branches) */

== Pre-release (stable only) ==
* Start the string freeze two weeks before the release.
* Do the pot update:
<nowiki>
scons pot-update update-po4a manual
git add -A
git commit -am "pot-update and regenerate doc files"</nowiki>
* Email the translator's mailing list stating that the string freeze is starting.

== Release (stable and master branches) ==
* Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:

cd data/tools/
make macro-reference.html
* If stable
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html
* If master
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference-1.<version>.html

* Regenerate the game credits and paste the contents to [[Credits]] on the wiki:

data/tools/about_cfg_to_wiki -w ./wesnoth > ./about.wiki

* Check the '''changelog_entries''' folder for entries and update the changelog as necessary.
* Run the following command:
<nowiki>/utils/update_appdata <version> packaging/org.wesnoth.Wesnoth.appdata.xml</nowiki>
* Run the pot update (second time if this is a stable release).
* Do the pre-tag commit (check a previous commit as an example - this removes the "+dev" suffix everywhere).
* The the post-tag commit (check a previous commit as an example - this re-adds the "+dev" suffix everywhere).
* Tag the pre-tag commit with:
<nowiki>git tag -a <version> -m "Wesnoth <version> (Alpha)" <commit hash></nowiki>
::- (Alpha)/(Beta) is only added for dev releases depending on where we are in the release cycle.
* Push the commits and the tag:
<nowiki>git push
git push origin <version></nowiki>
* Ping the packagers on Discord that the release has been tagged:
<nowiki>@packagers <version> has been tagged.</nowiki>
* Check that the new version is allowed on its respective multiplayer server.
* Update the header in Discord's #development channel.
* Upload master.zip and the patch to SourceForge to the respective version's folder for use by Android
** master.zip contains the folders
*** data (data/core/music/ is removed)
*** fonts
*** images
*** sounds
*** translations
** For the patch, go to packaging/android/ and run

<nowiki>./create_patch.sh oldtag newtag</nowiki>

Then upload the resulting patch.zip and manifest.txt next to master.zip.
* Upload source code tarball to SourceForge and files.wesnoth.org (done by loonycyborg).
* Send an email to the packagers mailing list (done by loonycyborg).
* Upload the release to the various places Wesnoth is distributed (Steam, itch.io, SourceForge, macOS App Store, Flathub, F-Droid).
** Windows/Linux - handled by loonycyborg.
** macOS - handled by hrubymar.
** Android (F-Droid) - handled by LumiousE
* Post the forum announcements.
* Update the Downloads wiki page.
** url: https://wiki.wesnoth.org/Download
** dev template: https://wiki.wesnoth.org/Template:DevDownload#Development_.281.15_branch.29
** stable template: https://wiki.wesnoth.org/Template:StableDownload
* Add the News forum post.
* Post the Discord announcement.
** Make sure to publish it.
** Short link is: '''<nowiki>https://r.wesnoth.org/t#####</nowiki>'''
* Post the itch.io devlog (copy of the Discord announcement).
* Update the wesnoth.org front page.
** See a previous version update commit to the '''wesmere''' repository.
** ssh into the website VM and execute the following shell commands (yes, it is specifically ''''make'''', not ''''make install''''!):
<nowiki>sudo -iu wesnoth
cd ~/git/wesmere/static
git pull
make</nowiki>
* Generate the Steam announcement by running the following command in your local wesnoth repository root:
<nowiki>python3 data/tools/steam-changelog changelog.md <version> > <version>.txt</nowiki>
* Post the Steam announcement.
* Log into Wesnoth's Steam page.
** Click "A Game Update".
** Pick "Small Update".
** Paste the output of of the above python command into the event description.
** Click "Link To Build" and select the appropriate branch.
** Edit the appropriate .xcf file from the [https://github.com/wesnoth/resources/tree/master/social-media-assets Resources repository] ('''wesnoth_event_header.xcf''' for stable releases, '''wesnoth_beta_header.xcf''' for development releases) and export it to PNG.
*** This requires the '''oldania''' font to be installed, which on Linux/Ubuntu-derivatives can be installed via the command:
<nowiki>apt install fonts-adf-oldania</nowiki>
* Post the announcement to Fosstodon.
* Post the announcement to Reddit. (Elvish_Hunter)
** Add the "Development release"/"Stable release" flair.
** Don't paste the link in the post, directly post it as a link.

== New Stable Series ==
=== Beta 1 ===
Write up the new Start page (ie: https://www.wesnoth.org/start/1.16/).

=== Beta 2 ===
Make the new Start page available to Translators.

=== RC1 ===
Before release, the new multiplayer server and add-ons server instances need to be setup. The server running the website status is owned by Iris - she needs to push updates to it.
* Multiplayer server
** Needs no changes since it goes to port 15000 and then that redirects based on version. The existing dev multiplayer server will be reused as the new stable instance.
** The Discord website status bot and the site status page (https://status.wesnoth.org/ - bin/valen.pl) need to be updated to rename the dev version to the stable version.
** A new stable multiplayer instance needs to be added to the alternate server.

* Add-ons server - The port is the version number, for example 1.16 is 15016, 1.18 is 15018, etc.
** C++ update (currently default_campaignd_port in addon/validation.cpp)
** Python update (data/tools/wesnoth/campaignserver_client.py)
** Website update (bin/valen.pl) in the valen repository to add the new instance.
** The Discord website status bot and the site status page (https://status.wesnoth.org/ - bin/valen.pl) need to be updated to add the new version.
** Add a 1.18 cron job for ~wesnoth/bin/update_addons in the websites VM and remove the 1.17 cron job.

* Flatpak
**

* Add screenshots to https://wiki.wesnoth.org/Screenshots

* Start page - soft link the folder from the repository to the folder that shows up on the actual website:
<nowiki>
cd /srv/www/html/start
ln -s /home/git/wesnoth/start/<version></nowiki>

* Update ci_main.yml to use the new branch instead of the master branch.

[[Category:Release_Notes]]

Template:DevDownload

2026-08-18T21:06:52Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.27 | filename=wesnoth-1.19.27-win64.exe |
hash=392eeb6fe448e72cfd43bc20318956287ae9bf59c66bce60d47115de0bb63545}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.27 | filename=Wesnoth_1.19.27.dmg |
hash=471feb944087f9985791f812de99d3792d3cc047eaacde8c92da764171b586de}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.27 | filename=wesnoth-1.19.27.tar.bz2 |
hash=05c82d2ee379bf80ee028b0f6f8554315c53675a131a30305b4301c01ea8af98}}

Template:StableDownload

2026-08-18T20:59:08Z

Pentarctagon:

<noinclude>
== Stable (1.18 branch) ==
</noinclude>
==== Windows (10 1903 and later, 64-bit only) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.8 | filename=wesnoth-1.18.8-win64.exe |
hash=464a2edfce8a0fe08e9956a363785938970254ee385672388bb8ba3556d8a09c}}

==== macOS (10.12 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.8 | filename=Wesnoth_1.18.8.dmg |
hash=aba4db430e18ed9bad7e98e645c620766be0757fbf03eb48d8205eb73471ee15}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.8 | filename=wesnoth-1.18.8.tar.bz2 |
hash=fce3bd71d4ed32c9d11c0f707d19743cec6adf5c34761fab94ab72754aaedd89}}

Template:DevDownload

2026-08-11T23:16:22Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.26 | filename=wesnoth-1.19.26-win64.exe |
hash=b77289f7a8233ff2af8a4d3d651d6bfd047bb923557e27471f5f18f870e4fd94}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.26 | filename=Wesnoth_1.19.26.dmg |
hash=8ced5829d75333acd16dcc0ae9a942f4c355609503e2692d2769797561d685b9}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.26 | filename=wesnoth-1.19.26.tar.bz2 |
hash=5bde64ae099cea7e469359f01ae350e9ba6c57f559cc66975a0f7bf7a2e6b6c6}}

Template:WML Tags

2026-08-09T17:17:41Z

Pentarctagon:

{| class="reference-sidebar"
|-
|
[[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit]]'''[[ReferenceWML|WML Tags]]'''
|-
|''A:''
[[AbilitiesWML#The .5Babilities.5D tag|abilities]],
[[CreditsWML#.5Babout.5D|about]],
[[AchievementsWML#.5Bachievement.5D|achievement]],
[[AchievementsWML#.5Bachievement_group.5D|achievement_group]],
[[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions|add_ai_behavior]],
[[AdvancedPreferenceWML|advanced_preference]],
[[UnitTypeWML#advancefrom|advancefrom]],
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AbilitiesWML#affect_adjacent|affect_adjacent]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],
[[StandardSideFilter#allied_with|allied_with]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta-Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML#The .5Banimation.5D tag|animation]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],
attack ([[ReplayWML#attack|replay]], [[UnitTypeWML#Attacks|weapon]]),
[[AnimationWML#short-attack|attack_anim]],
attacks ([[AbilitiesWML#The_.5Bspecials.5D_tag|special]], [[StatisticalScenarioWML#The_.5Bteam.5D_tag|stats]]),
[[AiWML#avoid|avoid]];
|-
|''B:''
[[UnitTypeWML#base_unit|base_unit]],
[[IntroWML#.5Bbackground_layer.5D|background_layer]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|berserk]],
[[BinaryPathWML|binary_path]],
[[InternalActionsWML#Flow_control_actions|break]],
[[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcancel_action.5D|cancel_action]],
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]],
[[InterfaceActionsWML#.5Bchange_theme.5D|change_theme]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[OptionWML#checkbox|checkbox]],
[[OptionWML#choice|choice]],
[[ReplayWML#choose|choose]],
[[PersistenceWML#WML Syntax|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],
[[GameConfigWML#Color_Palettes|color_palette]],
[[GameConfigWML#Color_Palettes|color_range]],
command ([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),
[[InternalActionsWML#Flow_control_actions|continue]],
[[CoreWML|core]],
[[CreditsWML#.5Bcredits_group.5D|credits_group]],
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];
|-
|''D:''
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage_type]],
[[AnimationWML#short-death|death]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|default]],
[[AnimationWML#short-defend|defend]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],
[[UnitsWML#defense|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML#attack|destination]],
[[CampaignWML#difficulty|difficulty]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|disable]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]],
[[DirectActionsWML#.5Bdo_command.5D|do_command]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]],
[[AnimationWML#short-draw_weapon|draw_weapon_anim]];
|-
|''E:''
[[EditorWML#The_.5Beditor_group.5D_tag|editor_group]],
[[EditorWML#The_.5Beditor_music.5D_tag|editor_music]],
[[EditorWML#The_.5Beditor_times.5D_tag|editor_times]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#Conditional Branches|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML#end_turn|replay]]),
[[StandardSideFilter#enemy_of|enemy_of]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Engines|engine]],
entry ([[CreditsWML#.5Bentry.5D|credits]], [[OptionWML|options]]),
[[EraWML|era]],
[[EventWML|event]],
[[StandardUnitFilter#filter_ability|experimental_filter_ability]],
[[StandardUnitFilter#filter_ability_active|experimental_filter_ability_active]],
[[AbilitiesWML#filter_specials|experimental_filter_specials]],
[[AnimationWML#short-extra|extra_anim]];
|-
|''F:''
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]],
[[ConditionalActionsWML#.5Bfalse.5D|false]],
[[PblWML#.5Bfeedback.5D|feedback]],
[[UnitTypeWML#variation|female]],
filter ([[FilterWML|concept]], [[EventWML#.5Bfilter.5D|event]]),
[[StandardUnitFilter#filter_adjacent|filter_adjacent]],
[[StandardLocationFilter#filter_adjacent_location|filter_adjacent_location]],
[[FilterWML#Filtering_Weapons|filter_attack]],
[[AbilitiesWML#filter_attacker|filter_attacker]],
[[AbilitiesWML#filter_base_value|filter_base_value]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[AbilitiesWML#filter_defender|filter_defender]],
[[AiWML#Filtering_Combat_with_the_attacks_Aspect|filter_enemy]],
[[StandardLocationFilter|filter_location]],
[[AbilitiesWML#filter_opponent|filter_opponent]],
[[AiWML#Filtering_Combat_with_the_attacks_Aspect|filter_own]],
[[StandardLocationFilter#filter_owner|filter_owner]],
[[StandardLocationFilter#filter_radius|filter_radius]],
[[SingleUnitWML#filter_recall|filter_recall]],
[[StandardUnitFilter|filter_second]],
[[FilterWML#Filtering_Weapons|filter_second_attack]],
[[AbilitiesWML#filter_self|filter_self]],
[[StandardSideFilter|filter_side]],
[[AbilitiesWML#filter_student|filter_student]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[FilterWML#Filtering_Weapons|filter_weapon]],
[[FilterWML#Filtering_on_WML_data|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[FontsWML|fonts]],
[[ConditionalActionsWML#.5Bfor.5D|for]],
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],
[[ConditionalActionsWML#.5Bfound_item.5D|found_item]],
[[AnimationWML#The .5Bframe.5D tag|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[PersistenceWML#WML Syntax|get_global_variable]],
[[AiWML#The_.5Bgoal.5D_Tag|goal]],
[[DirectActionsWML#.5Bgold.5D|gold]],
[[InterfaceActionsWML#objectives-gold_carryover|gold_carryover]];
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[StandardSideFilter#has_ally|has_ally]],
[[StandardUnitFilter#has_attack|has_attack]],
[[StandardSideFilter#has_unit|has_unit]],
[[ConditionalActionsWML#.5Bhas_achievement.5D|has_achievement]],
[[ConditionalActionsWML#.5Bhave_location.5D|have_location]],
[[ConditionalActionsWML#.5Bhave_side.5D|have_side]],
[[ConditionalActionsWML#.5Bhave_unit.5D|have_unit]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[AnimationWML#short-healed|healed_anim]],
[[AnimationWML#short-healing|healing_anim]],
[[AbilitiesWML#The_.5Babilities.5D_tag|heals]],
[[UnitsWML#.5Bhide_help.5D|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],
[[AbilitiesWML#The_.5Babilities.5D_tag|hides]];
|-
|''I:''
[[AnimationWML#short-idle|idle_anim]],
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#Conditional Branches|animation]], [[IntroWML|intro]]),
[[AbilitiesWML#The_.5Babilities.5D_tag|illuminates]],
image ([[IntroWML#.5Bimage.5D|intro]], [[TerrainGraphicsWML#The_.5Bimage.5D_subtag|terrain]]),
[[ReplayWML#init_side|init_side]],
[[VariablesWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[InterfaceActionsWML#.5Bitem.5D|item]],
[[EditorWML#The_.5Bitem_group.5D_tag|item_group]];
|-
|''J:''
[[UnitsWML#jamming_costs|jamming_costs]],
[[InternalActionsWML#join|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|killed]];
|-
|''L:''
[[InterfaceActionsWML#.5Blabel.5D|label]],
[[LanguageWML|language]],
[[SideWML#leader|leader]],
[[AiWML#leader_goal|leader_goal]],
[[AbilitiesWML#The_.5Babilities.5D_tag|leadership]],
[[AnimationWML#short-leading|leading_anim]],
[[AnimationWML#short-levelin|levelin_anim]],
[[AnimationWML#short-levelout|levelout_anim]],
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],
[[AI_Recruitment#instructions-limit|limit]],
[[InternalActionsWML#set_variables-literal|literal]],
[[AddonsWML#load_resource|load_resource]],
[[LocaleWML|locale]],
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],
[[LuaWML|lua]];
|-
|''M:''
[[UnitTypeWML#variation|male]],
[[ReplayWML#map_data|map_data]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[Micro AIs|micro_ai]],
[[AnimationWML#The .5Bframe.5D tag|missile_frame]],
[[ModificationWML|modification]],
[[SingleUnitWML#modifications|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[AddonsWML#modify_unit_type|modify_unit_type]],
[[ReplayWML#move|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[AnimationWML#short-movement|movement_anim]],
[[UnitsWML#movement_costs|movement costs]],
[[UnitsWML#.5Bmovetype.5D|movetype]],
[[ScenarioWML#The_.5Bmultiplayer.5D_tag|multiplayer]],
[[EraWML#Defining_Factions|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
[[ConditionalActionsWML#Meta-Condition_Tags|not]],
[[InterfaceActionsWML#objectives-note|note]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#objectives-objective|objective]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[DirectActionsWML#.5Bon_undo.5D|on_undo]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML#.5Bmessage.5D|option]],
[[OptionWML|options]],
[[ConditionalActionsWML#Meta-Condition_Tags|or]];
|-
|''P:''
[[IntroWML#.5Bpart.5D|part]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]],
[[DirectActionsWML#.5Bpetrify.5D|petrify]],
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]],
[[AnimationWML#short-post_movement|post_movement_anim]],
[[AnimationWML#short-pre_movement|pre_movement_anim]],
[[InternalActionsWML#.5Bfire_event.5D|primary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|primary_unit]],
[[InterfaceActionsWML#.5Bprint.5D|print]],
[[DirectActionsWML#.5Bprogress_achievement.5D|progress_achievement]],
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];
|-
|''R:''
[[UnitsWML#.5Brace.5D|race]],
[[InternalActionsWML#.5Brandom_placement.5D|random_placement]],
recall ([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML#recall|replay]]),
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|recalls]],
[[ReplayWML#recruit|recruit]],
[[AnimationWML#short-recruit|recruit_anim]],
[[AnimationWML#short-recruiting|recruiting_anim]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|recruits]],
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[AbilitiesWML#The_.5Babilities.5D_tag|regenerate]],
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]],
[[DirectActionsWML#.5Bremove_object.5D|remove_object]],
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]],
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]],
[[DirectActionsWML#.5Bremove_trait.5D|remove_trait]],
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]],
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]],
[[ReplayWML|replay]],
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]],
resistance ([[AbilitiesWML#The_.5Babilities.5D_tag|ability]], [[UnitsWML#resistance|unit]]),
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],
[[ThemeWML#The_toplevel_.5Btheme.5D_tag|resolution]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],
[[InternalActionsWML#Flow_control_actions|return]],
[[InternalActionsWML#.5Brole.5D|role]],
[[TerrainMaskWML#rule|rule]];
|-
|''S:''
[[ScenarioWML#The_.5Bscenario.5D_tag|scenario]],
[[InterfaceActionsWML#.5Bscreen_fade.5D|screen_fade]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]],
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_unit]],
[[HelpWML#section|section]],
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]],
[[ReplayWML#sequence|sequence]],
[[DirectActionsWML#.5Bset_achievement.5D|set_achievement]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[PersistenceWML#WML_Syntax|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]],
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[EffectWML#set_specials|set_specials]],
[[InternalActionsWML#.5Bset_variable.5D|set_variable]],
[[InternalActionsWML#.5Bset_variables.5D|set_variables]],
[[AnimationWML#short-sheath_weapon|sheath_weapon_anim]],
show_if ([[InterfaceActionsWML#.5Bmessage.5D|message]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]],
[[AbilitiesWML#The_.5Babilities.5D_tag|skirmisher]],
[[OptionWML#slider|slider]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]],
[[InterfaceActionsWML#.5Bsound.5D|sound]],
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]],
source ([[ReplayWML#attack|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),
[[UnitTypeWML#Special Notes|special_note]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]],
[[InternalActionsWML#set_variables-split|split]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Stages|stage]],
[[AnimationWML#short-standing|standing_anim]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[SingleUnitWML#status|status]],
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]],
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]],
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]],
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]],
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]],
[[InternalActionsWML#.5Bstore_unit_defense.5D|store_unit_defense]],
[[InternalActionsWML#.5Bstore_unit_defense_on.5D|store_unit_defense_on]],
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],
[[IntroWML|story]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]],
[[AchievementsWML#.5Bsub_achievement.5D|sub_achievement]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]],
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];
|-
|''T:''
[[DirectActionsWML#.5Btunnel.5D|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),
[[AnimationWML#short-teleport|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]],
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],
[[TerrainGraphicsWML|terrain_graphics]],
[[TerrainMaskWML|terrain_mask]],
[[TerrainWML|terrain_type]],
[[ScenarioWML#The_.5Btest.5D_tag|test]],
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],
[[TestWML#The_.5Btest_do_attack_by_id.5D_tag|test_do_attack_by_id]],
[[InterfaceActionsWML#message-text_input|text_input]],
[[GettextForWesnothDevelopers#The_textdomain_tag|textdomain]],
[[ThemeWML|theme]],
[[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML#The_.5Btile.5D_subtag|tile]],
[[TimeWML|time]],
[[DirectActionsWML#.5Btime_area.5D|time_area]],
[[HelpWML#topic|topic]],
[[HelpWML#toplevel|toplevel]],
[[UnitsWML#.5Btrait.5D|trait]],
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]],
[[InternalActionsWML#.5Bfind_path.5D|traveler]],
[[ConditionalActionsWML#.5Btrue.5D|true]],
[[DirectActionsWML#.5Btunnel.5D|tunnel]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]],
unit ([[DirectActionsWML#.5Bunit.5D|action]], [[SingleUnitWML|scenario]]),
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]],
[[UnitTypeWML|unit_type]],
[[InternalActionsWML#.5Bunit_worth.5D|unit_worth]],
[[UnitsWML|units]],
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]],
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]],
[[InternalActionsWML#.5Bunsynced.5D|unsynced]];
|-
| ''V:''
[[InternalActionsWML#set_variables-value|value]],
[[ConditionalActionsWML#.5Bvariable.5D|variable]],
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],
[[TerrainGraphicsWML#variant|variant]],
[[UnitTypeWML#variation|variation]],
[[AnimationWML#short-victory|victory_anim]],
[[SideWML#village|village]],
[[UnitsWML#vision_costs|vision_costs]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]],
[[SchemaWML|wml_schema]];
|-
| ''Z:''
[[InterfaceActionsWML#.5Bzoom.5D|zoom]];
|}<includeonly>[[Category:WML Reference]]</includeonly><noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the [[ReferenceWML|WML reference]] pages.</noinclude>

CampaignWML

2026-07-10T18:49:50Z

Pentarctagon:

{{WML Tags}}



This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.

==The [campaign] Tag==

The following keys and tags are recognized in '''[campaign]''' tags, in addition to all the common [[AddonsWML|addon module keys and tags]]:
* '''icon''': the image displayed in the campaign selection menu
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)
* '''background''': {{DevFeature1.15|9}} the image used as a backdrop for the Campaigns menu (typically a high resolution image intended for displaying fullscreen in story screens). If blank or unspecified, a stock story background from core is used.
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".
* '''define''': The preprocessor symbol that will be defined for this campaign. All other campaign-specific code should be contained in an ''#ifdef'' checking for this symbol.
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. (In the past, this tag was used to define common optional advancements, but that use is deprecated. There are now macros to add those advancements defined in [https://www.wesnoth.org/macro-reference.html#file:optional_unit_advancements.cfg data/core/macros/optional_unit_advancements.cfg].)
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [https://www.wesnoth.org/macro-reference.html#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] description=
* {{anchor|difficulty|'''[difficulty]'''}}: {{DevFeature1.13|2}} specifies a single campaign difficulty. The difficulties are expected to be ordered from easiest to hardest. The following keys are accepted:
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.
** '''image''': the image to display for this difficulty in the selection menu
** '''label''': a flavor label describing this difficulty. Displayed second after the image
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.
** '''auto_markup''': {{DevFeature1.15|0}} By default, the description is shown in small, gray text within parentheses. Setting '''auto_markup=no''' disables these, so no markup will be applied implicitly. Any markup in '''description''' will be honored regardless of this setting.
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) {{DevFeature1.14|6}} a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.
* '''year''': shortcut for specifying both '''start_year''' and '''end_year''', for campaigns that happen inside a single calendar year. Ignored if '''start_year''' is given.
* '''[about]''': inserts your own credits into the game's list of credits. See [[CreditsWML]] for syntax.
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. {{DevFeature1.15|6}} This value is capped at 5000 (5 seconds).
The following keys are additionally recognized in multiplayer:
* '''min_players''': Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.
* '''max_players''': Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either '''min_players''' or 2, whichever is higher.
* '''allow_era_choice''': Whether to allow era selection (when set to ''yes'') or hide it and use a default one when creating a game (when set to ''no''). Defaults to ''yes''.
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.

== See Also ==

* [[PreprocessorRef]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[PblWML]]

[[Category: WML Reference]]

WesnothTranslations

2026-07-05T06:35:42Z

Pentarctagon:

== Translations ==

Wesnoth is currently being translated into the following languages. These languages are active and have a maintainer.
{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AncientGreekTranslation|Ancient Greek]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[BengaliTranslation|Bengali]] || Subhraman Sarkar (LumiousE) || lumious_e on Discord
|-
| [[CatalanTranslation|Catalan]] || Arnau Vàzquez Palma || [mailto:arnauvpATmurenaDOTio]
|-
| [[ChineseTranslation|Chinese]] || CloudiDust || [mailto:cloudidustATgmailDOTcom]
|-
| [[CzechTranslation|Czech]] || Michal Žejdl || [mailto:lachimATemerDOTcz]
|-
| [[EnglishGBTranslation|English (GB)]] || Wedge009 || [mailto:wedge009ATwedge009DOTnet]
|-
| [[FinnishTranslation|Finnish]] || Jaakko Saarikko (styxnix) || [mailto:jaakkoDOTsaarikkoATprotonmailDOTcom]
|-
| [[FrenchTranslation|French]] || demario || [mailto:wesnothfr-request@lists.tuxfamily.org?subject=subscribe mailing list]
|-
| [[GalicianTranslation|Galician]] || Adrian Chaves || [mailto:adrianATchavesDOTio]
|-
| [[GermanTranslation|German]] || Aaron Winter (Bitron) ||
|-
| [[GreekTranslation|Greek]] || Spiros Ioannou || [mailto:sivannATgmailDOTcom]
|-
| [[HungarianTranslation|Hungarian]] || Berda Jenő (bigbilly) || [mailto:big4billyATgmailDOTcom]
|-
| [[ItalianTranslation|Italian]] || Antonio Rosella || [mailto:arosellaATyahooDOTcom]
|-
| [[PolishTranslation|Polish]] || ForPeace || [https://forums.wesnoth.org/viewtopic.php?f=7&t=3796 forum thread]
|-
| [[PortugueseTranslation|Portuguese Brazilian]] || Andrei Machado || [mailto:andreisp.machadoATyahooDOTcom]
|-
| [[RussianTranslation|Russian]] || [[User:Alexinor|Alexinor]] || [mailto:obolonkinATprotonDOTme]
|-
| [[SerbianTranslation|Serbian]] || Vlastimir Krstonosic || [mailto:krstonosicvlastimirATgmailDOTcom]
|-
| [[SpanishTranslation|Spanish]] || Sebastián Lecchini (Sebas38760) || [mailto:sebas38760ATgmailDOTcom]
|}

These languages have a maintainer, but have not made any commits for over a year (as of summer 2026).

{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[ArabicTranslation|Arabic]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[BulgarianTranslation|Bulgarian]] || Ivan Petrov (TheWhiteKnight) || [mailto:vankata_petrovATabvDOTbg]
|-
| [[ChineseTaiwanTranslation|Chinese (Taiwan)]] || 楊綮銘 (Taiwan) || [mailto:steven2880ATgmailDOTcom]
|-
| [[DutchTranslation|Dutch]] || Merijn de Vet || [mailto:merijndevetAThotmailDOTcom]
|-
| [[EnglishShawTranslation|English (Shaw)]] || Arc Riley || [mailto:ArcRileyATubuntuDOTcom]
|-
| [[Esperanto_translation|Esperanto]] || Mariano Street (mctpyt) || [mailto:mctpytATprotonDOTme]
|-
| [[IndonesianTranslation|Indonesian]] || Irsyad Musthafa || [mailto:sevennightmareATtutanotaDOTde]
|-
| [[JapaneseTranslation|Japanese]] || Hironori Fujimoto (RatArmy) || [mailto:broadbarredfirefishATgmailDOTcom]
|-
| [[KoreanTranslation|Korean]] || mistzone || [mailto:drier22ATgmailDOTcom]
|-
| [[LatinTranslation|Latin]] || Daniel Faustmann || [mailto:donnerstag.freitag213@gmail.com]
|-
| [[NorwegianTranslation|Norwegian]] || Bloodaxe || [mailto:bloodaxenor@protonmail.com]
|-
| [[PortugueseContinentalTranslation|Portuguese (European)]] || trewe || [mailto:sjrs456ATyahooDOTfr]
|-
| [[Scottish_Gaelic_Translation|Scottish Gaelic]] || GunChleoc || [mailto:fiosAIGforamnagaidhligDOTnet]
|-
| [[SlovakTranslation#Preklad|Slovak]] || Stanislav Hoferek || [mailto:shoferek@gmail.com]
|-
| [[SwedishTranslation|Swedish]] || Alex Alowersson (fluxbird) || [mailto:alexalowersonATgmailDOTcom]
|-
| [[TurkishTranslation|Turkish]] || Nilgün Belma Bugüner || [mailto:nilgunATbelgelerDOTorg]
|-
| [[UkrainianTranslation|Ukrainian]] || Oleksii Okhrimenko (lexa04) || Discord: amakri Email: [mailto:ohrimaleATgmailDOTcom]
|}

Currently inactive translations. If you wish to improve some of these languages (or one of the above maintainers is not responsive), contact Ivanovic on the [https://wiki.wesnoth.org/Support Wesnoth Discord channel].

{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AfrikaansTranslation|Afrikaans]] || None || N/A
|-
| [[BasqueTranslation|Basque]] || None || N/A
|-
| [[BurmeseTranslation|Burmese]] || None || N/A
|-
| [[CroatianTranslation|Croatian]] || None || N/A
|-
| [[DanishTranslation|Danish]] || None || N/A
|-
| [[HebrewTranslation|Hebrew]] || None || N/A
|-
| [[IcelandicTranslation|Icelandic]] || None || N/A
|-
| [[IrishTranslation|Irish]] || None || N/A
|-
| [[LatvianTranslation|Latvian]] || None || N/A
|-
| [[LithuanianTranslation|Lithuanian]] || None || N/A
|-
| [[MarathiTranslation|Marathi]] || None || N/A
|-
| [[MacedonianTranslation|Macedonian]] || None || N/A
|-
| [[OldEnglishTranslation|Old English]] || None || N/A
|-
| [[RACVTranslation|RACV]] || None || N/A
|-
| [[RomanianTranslation|Romanian]] || None || N/A
|-
| [[SlovenianTranslation|Slovenian]] || None || N/A
|-
| [[SpanishLatinAmericanTranslation|Spanish (Latin American)]] || None || N/A
|-
| [[ValencianTranslation|Valencian]] || None || N/A
|-
| [[VietnameseTranslation|Vietnamese]] || None || N/A
|}

== Mailing List ==

There now is a mailing list dedicated to translation matters. It is mainly intended to be used for informing translation maintainers about important changes, to announce string freezes and other special things. Everyone is free to subscribe to this list.

* [https://groups.io/g/wesnoth-translations From February 2025]
* [https://listengine.tuxfamily.org/wesnoth.org/i18n/ List info, how to subscribe, and archives from April 2022]
* [https://mailman.wesnoth.org/pipermail/i18n/ Old list archives (up until April 2022)]

Please keep in mind that this list is not meant for discussing changes for one single translation but instead subjects which are relevant to all translations.

== See also ==

* [[WesnothTranslationsHowTo]]
* [[ImageLocalization]]
* [[GetText]]
* [http://gettext.wesnoth.org Translations statistics (stable)]
* [http://gettext.wesnoth.org/index.php?version=trunk&package=alloff Translations statistics (development)]
* [[GettextForTranslators#For_add-ons|Translating User Made Campaigns and add-ons]]
* [[SpellingMistakes]]
* [[CharactersStorys| Character descriptions for Translators (Spoiler Warning)]]
* [[Poetry of Wesnoth Translations]]

[[Category:Translations|*]]

Maintenance tools

2026-07-03T16:36:50Z

Pentarctagon: /* wmllint */

<div class="floatright"> __TOC__ </div>

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These
are:

; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.

; wmllint: a utility for sanity-checking WML syntax and porting your old WML to the current version of WML.

; wmlindent: a utility for reindenting WML to a uniform style.

; GUI.pyw: a graphical interface

== General Information ==

You will need a Python 3 interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python 3 installed; for Windows it's a free download
from http://www.python.org. You will also need to know how to run command-line tools on your system.

If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.16-tools (or the convenient version).
sudo apt install wesnoth-1.16-tools

All three tools will require you to supply a directory list. This is a set of directories containing the WML files you want to work on.

This page is intended as documentation for users.

Note to Windows Users: This means you have to run it from the '''Command Line'''. The command line may be reached by hitting Start, then Run, then "cmd" or "command" depending on your version of Windows.

Example uses:
python wmllint path\to\files
python wmlindent path\to\files

Another example:
"C:\Program Files\Python3.7\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns
(You have to specify the full directory path to the executable if you don't have your environment variables set up correctly).
The first thing you type is the path to your python executable, followed by a space. The second thing you type is the path to the desired script to run, followed by a space. The third thing you type is the path to the folder (or file) to be processed.

'''A convenient way of running wmllint''' on Linux (Debian or Ubuntu) and Windows in comparison, '''Linux''':

Assuming we're working with wesnoth 1.16 or more advanced versions.
python3 /usr/share/games/wesnoth/1.16/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.16/data/core ~/.local/share/wesnoth/1.16/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
I have these commands inside of a file named
wmllint_dryrun_ASC.sh
and execute it by opening a shell (=terminal, console, command window, bash,...), navigating into the directory with that file and typing
bash wmllint_dryrun_ASC.sh
The python3 command should be automatically known on Debian. The path to the script tells the python interpreter what to execute. --dryrun: A wmllint option, see below. The path to the core files is needed to let wmllint know about e.g. defined core units, followed by the path to the add-on that shall be checked; the last two commands cause the result of the wmllint usage to be written into those files in the same directory as the script.
'''Windows''', this is logically exactly the same as the Linux shell script above, so if you are on a Mac you can probably conclude how you need to adapt the paths:
E:\Python37\python.exe E:\Programme\Wesnoth_1.16_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.16_git\data\core E:\Programme\Wesnoth_1.16_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
This is the content of a .txt file, whose extension I rename to .bat and double-click onto it. Opening a command window is not needed this way.
Since Python isn't natively installed on windows and I don't have environment variables set, the full path to python.exe is given. If your directories contain spaces it may help to include the path in quotes:
"C:\Programs\Battle for Wesnoth 1.16\data\tools\wmllint"
Remember that you do not need to enter all of the commands/paths at once. If it doesn't work, start with only "python" or "C:\Python37\python.exe" or the like and interpret the error messages that you get. If you get an "unknown command", python isn't installed or environment variables aren't set correctly. After that, you can add the later commands one by one.

== wmlscope ==

The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic (see [https://github.com/wesnoth/wesnoth/issues/5332 issue 5332] for more info). They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.

<tt>wmlscope</tt> also checks macro invocations for consistency. It will complain
if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

<table class="wikitable"><tr>
<th>Type</th>
<th>Meaning</th>
<th>Formals requiring this type</th>
<th>Literals of this type</th>
</tr>
<tr>
<td>side</td>
<td>a single side number</td>
<td>SIDE, *_SIDE, SIDE[0-9]</td>
<td>a numeric or "global"</td>
</tr>
<tr>
<td>numeric</td>
<td>a numeric integer literal</td>
<td>SIDE, X, Y, RED, GREEN, BLUE, TURN, PROB, LAYER, TIME, *_SIDE, *NUMBER, *AMOUNT, *COST, *RADIUS, *_X, *_Y, *_INCREMENT, *_FACTOR, *_TIME, *_SIZE, DURATION</td>
<td>\-?[0-9]+</td>
</tr>
<tr>
<td>percentage</td>
<td>a percentage</td>
<td>*PERCENTAGE</td>
<td>a numeric or 0\.[0-9]+</td>
</tr>
<tr>
<td>position</td>
<td>a single x,y coordinate</td>
<td>POSITION, *_POSITION, BASE</td>
<td>-?[0-9]+,-?[0-9]+</td>
</tr>
<tr>
<td>span</td>
<td>a set of coordinates or coordinate ranges</td>
<td>*_SPAN</td>
<td>a numeric, position or ([0-9]+\-[0-9]+,?|[0-9]+,?)+</td>
</tr>
<tr>
<td>alliance</td>
<td>a set of side numbers</td>
<td>SIDES, *_SIDES</td>
<td>a span, or the empty string</td>
</tr>
<tr>
<td>range</td>
<td>an attack range</td>
<td>RANGE</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>alignment</td>
<td>an alignment keyword</td>
<td>ALIGN</td>
<td>"lawful" or "neutral" or "chaotic"</td>
</tr>
<tr>
<td>types</td>
<td>a set of unit types</td>
<td>TYPES</td>
<td>a shortname, name, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>terrain_pattern</td>
<td>a set of terrain codes to filter</td>
<td>ADJACENT*, TERRAINLIST*, *TERRAIN_PATTERN, RESTRICTING</td>
<td>a terrain_code or name</td>
</tr>
<tr>
<td>terrain_code</td>
<td>a single terrain code, perhaps with overlay</td>
<td>TERRAIN*, *TERRAIN</td>
<td>a shortname or (\*|[A-Z][a-z]+)\^([A-Z][a-z\\|/]+\Z)?</td>
</tr>
<tr>
<td>shortname</td>
<td>a terrain code or a short, capitalized variable name</td>
<td></td>
<td>[A-Z][a-z][a-z]?</td>
<tr>
<td>name</td>
<td>a name or identifier</td>
<td>NAME, VAR, IMAGESTEM, ID, FLAG, *_NAME, *_ID, NAMESPACE, BUILDER, *_VAR</td>
<td>anything without spaces that matches no other type</td>
</tr>
<tr>
<td>optional_string</td>
<td>a string value (may be empty)</td>
<td>ID_STRING, NAME_STRING, DESCRIPTION, IPF</td>
<td>a string, or the empty string</td>
</tr>
<tr>
<td>string</td>
<td>a nonempty string not matching any of the preceding types</td>
<td>STRING, TYPE, TEXT, *_STRING, *_TYPE, *_TEXT</td>
<td>a shortname, a name, a stringliteral, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>stringliteral</td>
<td>a string in doublequotes or a translated string</td>
<td></td>
<td>".*" or _.* but not _[a-z].*</td>
</tr>
<tr>
<td>image</td>
<td>an image path, perhaps with [[ImagePathFunctionWML|image path functions]]</td>
<td>*IMAGE, PROFILE</td>
<td>[A-Za-z0-9{}.][A-Za-z0-9_/+{}.-]*\.(png|jpg)(?=(~.*)?)</td>
</tr>
<tr>
<td>sound</td>
<td>a music or sound filename</td>
<td>MUSIC, SOUND</td>
<td>string ending with ".wav" or ".ogg"</td>
</tr>
<tr>
<td>filter</td>
<td>[[FilterWML|WML filter]]</td>
<td>FILTER</td>
<td>any non-quoted string containing "="</td>
</tr>
<tr>
<td>WML</td>
<td>arbitrary WML fragment</td>
<td>WML, *_WML</td>
<td>any non-quoted string containing "=", or the empty string</td>
</tr>
<tr>
<td>affix</td>
<td>a prefix, suffix, or infix for a variable name</td>
<td>AFFIX, *AFFIX, POSTFIX, ROTATION</td>
<td>a shortname or name, or the empty string</td>
</tr>
<tr>
<td>any</td>
<td>anything</td>
<td>*VALUE, [ARS][0-9]</td>
<td>anything</td>
</tr>
</table>

If the actual argument is a macro call {.*}, then it matches any formal. Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in data/tools/Makefile of the source distribution. Here are some of those reports:

; make unresolved: Report on unresolved macro calls and resource references; also report macro argument-type mismatches. (This is what you are most likely to want to do).

; make all: Report all macro and resource file references, not just unresolved ones.

; make collisions: Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand
[http://docs.python.org/lib/re-syntax.html Python regular expressions].

; -h, --help: Emit a help message and quit
; -c, --crossreference: Report resolved macro references (implies <tt>-w 1</tt>)
; -C, --collisions: Report duplicate resource files
; -d, --deflist: Make definition list. (This one is for campaign server maintainers.)
; -e regexp, --exclude regexp: Ignore files matching the specified regular expression.
; -f dir, --from dir: Report only on macros defined under dir
; -l, --listfiles: List files that will be processed
; -r ddd, --refcount=ddd: Report only on macros with references in exactly ddd files.
; -t TYPELIST, --typelist TYPELIST: List actual & formal argtypes for calls in fname
; -u, --unresolved: Report unresolved macro references
; -w, --warnlevel: Set to 1 to warn of duplicate macro definitions
; -p, --progress: Show progress
; --force-used reg: Ignore reference count 0 on names matching regexp
; --extracthelp: Extract help from macro definition comments.
; --unchecked: Report all macros with untyped formals.
; --version: show program's version number and exit

These options are used with a list of directories as arguments; if none is given,
<tt>wmlscope</tt> behaves as though the current directory had been specified as a
single argument. Each directory is treated as a separate domain for
macro and resource visibility purposes.

<tt>wmlscope</tt> recognizes two kinds of namespace, exporting and non-exporting.
Exporting namespaces make all their resources and macro names
globally visible. You can make a namespace exporting by embedding
a comment like this in it:

# wmlscope: export=yes

Wesnoth core data is an exporting namespace. Campaigns are non-exporting;
they should contain the declaration

# wmlscope: export=no

somewhere. <tt>wmlscope</tt> will complain when it sees a namespace with no export
property, then treat it as non-exporting.

You can tell <tt>wmlscope</tt> to ignore stretches of config files
with the following magic comments:

# wmlscope: start ignoring
# wmlscope: stop ignoring

Similarly, you can tell <tt>wmlscope</tt> to ignore multiple or duplicate macro
definitions in a range of lines with the following magic comments:

# wmlscope: start conditionals
# wmlscope: stop conditionals

The following magic comment:

# wmlscope: prune FOOBAR

will cause <tt>wmlscope</tt> to forget about all but one of the definitions of
<tt>FOOBAR</tt> it has seen. This will be useful mainly for symbols that have
different definitions enabled by an <tt>#ifdef</tt>.

Due to a preprocessor limitation, inline macros cannot contain a documentation
string. If you need to document these macros in the HTML macro reference, you
can use the following directive:

# wmlscope: docstring FOOBAR

The docstring for the FOOBAR macro will be collected until a non-comment line,
a <tt>#define</tt> or another <tt># wmlscope: docstring</tt> are found. External
docstrings '''''must''''' be defined before the macro to which they refer; defining
two or more external docstrings keeps only the most recent one, but having both an
external and an internal docstring is allowed (in this case, the internal one
will be appended to the external one in the macro reference).

This tool does catch one kind of implicit reference: if an attack name
is specified but no icon is given, the attack icon will default to
a name generated from the attack name. This behavior can be suppressed
by adding a magic comment containing the string "no-icon" to the <tt>name=</tt>
line.

The checking done by this tool has a couple of flaws:

(1) It doesn't actually evaluate file inclusions. Instead, any
macro definition satisfies any macro call made under the same
directory. Exception: when an <tt>#undef</tt> is detected, the macro is
tagged local and not visible outside the span of lines where it was
defined.

(2) It doesn't read <tt>[binary_path]</tt> tags, as this would require
implementing a WML parser. Instead, it assumes that a resource-file
reference can be satisfied by any matching image file from anywhere
in the same directory it came from. The resources under the '''''first'''''
directory argument (only) are visible everywhere.

(3) A reference with embedded {}s in a macro will have the macro's
formal args substituted in at WML evaluation time. Instead, this
tool treats each {} as a .* wildcard and considers the reference to
match '''''every''''' resource filename that matches that pattern.
Under appropriate circumstances this might report a resource filename
statically matching the pattern as having been referenced even
though none of the actual macro calls would actually generate it.

Problems (1) and (2) imply that this tool might conceivably report
that a reference has been satisfied when under actual
WML-interpreter rules it has not.

The reporting format is compatible with GNU Emacs compile mode.

For debugging purposes, an in-line comment of the form

# wmlscope: warnlevel NNN

sets the warning level.

== wmllint ==

<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:

* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.

* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. If you port such old code, use <tt>wmllint-1.4</tt>, which is located in the same directory as <tt>wmllint</tt>. It will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

<tt>wmllint</tt> also performs various sanity-checking operations, reporting:

* unbalanced tags
* strings that need a translation mark and do not have them
* strings that have a translation mark and should not
* translatable strings containing macro references
* filter references by description= (id= in 1.5) not matched by an actual unit
* abilities or traits without matching special notes, or vice-versa
* consistency between recruit= and recruitment_pattern= instances
* double space after punctuation in translatable strings.
* unknown races or movement types in units

<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

; -h, --help: Emit a help message and quit.
; -c, --clean: Clean up -bak files.
; -D, --diffs: Display diffs between converted and unconverted files.
; -d, --dryrun: List changes (-v) but don't perform them.
; -r, --revert: Revert the conversion from the -bak files.
; -m, --missing: Warn about tags without side= keys now applying to all sides.
; -s, --stripcr: Convert DOS-style CR/LF to Unix-style LF.
; -v, --verbose: Set verbosity; more details below.
; -K, --known: Suppress check for unknown unit types, recruits, races, scenarios, etc.
; --version: show program's version number and exit
; --config: allows specifying directories to include ('''include_dirs'''), directories to exclude ('''ignore_directories'''), and files to exclude ('''ignore_files''').

The verbosity option works like this:

; -v: lists changes.
; -v -v: warns of maps already converted.
; -v -v -v: names each file before it's processed.
; -v -v -v -v: shows verbose parse details (developers only).

The recommended procedure is this:

# Run it with --dryrun first to see what it will do.
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
# Eyeball the changes with the --diff option.
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
# Test the conversion.
# Use either --clean to remove the -bak files or --revert to undo the conversion.

wmllint supports a number of magic comments to customize its behaviour and avoid false positives. Almost all magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. These are all documented at the top of the wmllint tool itself in the MAGIC COMMENTS section: https://github.com/wesnoth/wesnoth/blob/master/data/tools/wmllint

=== Explanations of <tt>wmllint</tt> diagnostics ===
Some <tt>wmllint</tt> diagnostics may require further explanation for UMC authors to understand; this section will be for providing such explanations, and descriptions of how to solve and/or silence them.

In these, <code>%s</code> will be replaced by a string. When the recommended solution also includes a <code>%s</code>, it's a suggestion to copy the string from the error message into your code.

* <code>nonstandard word-wrap style within message</code>: This message meant there was an unexpected newline character within a <code>[message]</code> tag. However, this check was removed in the 1.15.10 release. Pre-1.15.10, add-on developers could silence by putting a <code># wmllint: display on</code> comment before the string and a <code># wmllint: display off</code> comment after the string, however, post-1.15.10, this is no longer necessary.
* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>unknown speaker '%s' of [message]</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the speaker is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is SPEAKER</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>unknown '%s' referred to by id</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the unit is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is UNIT</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>%s has unknown advancements</code> (in cases where you'd think the advancement ''would'' be known): This means the unit has an advancement that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load mainline units for checking advancements. Note that it's also possible that you just made typo, too, so be sure to check your spelling. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>.description may need hand fixup</code>: This one comes from mucking around with the <code>.description</code> field of unit data manually in a hackish fashion. There isn't really much of a way to work around it, besides just the "don't do that" solution.
* <code>tag stack nonempty (%s) at end of file.</code>: This means that you have unbalanced tags somewhere in the file, e.g. an opener without a closer, or vice versa. This can often be seen when defining macros for unit abilities. A way to fix this warning is to wrap the section with unbalanced tags with a <code># wmllint: unbalanced-on</code> magic comment beforehand and a <code># wmllint: unbalanced-off</code> magic comment afterwards. As having unbalanced tags will also cause issues for other WML maintenance tools, such as <tt>wmlindent</tt> and <tt>wmlxgettext</tt>, you may also want to add separate magic comments for each of them (see their documentation for the form they take).
* <code>unit declaration without side attribute</code>: the default side for a unit declaration when left implicit is side 1. Specify your unit sides explicitly to solve this.
* <code>no %s units recruitable at difficulty %s</code> (even when there are such units recruitable): This diagnostic has to do with matching the <code>usage</code> key of units recruitable by an AI side with their <code>recruitment_pattern</code>. It means the unit has a usage that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can know which mainline units are recruitable. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown movement type</code> (even when you'd think that that movement type ''would'' actually be known): This means the unit has a movetype that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline movement types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown race</code> (even when you'd think that that race ''would'' actually be known): This means the unit has a race that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline races. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>derivation of %s from %s does not resolve</code> (even when you'd think it would): This means that a unit using the [[UnitTypeWML#Other_tags|[base_unit]]] tag specifies a unit ID in that tag that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the core units for its derivation checks. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>[advancefrom] needs to be manually updated to [modify_unit_type] and moved into the _main.cfg file</code>: This one is pretty self-explanatory: [[UnitTypeWML#Unit_Type|[advancefrom]]] was deprecated in [https://github.com/wesnoth/wesnoth/commit/3950f40f3f0483032bc70b3e57166bd355acd9fc commit 3950f40] due to [https://github.com/wesnoth/wesnoth/issues/3955 issue #3955], and in fact doesn't even work anymore (in 1.16) as per [https://github.com/wesnoth/wesnoth/issues/6204 issue #6204]. The main reason <tt>wmllint</tt> can't fix this automatically is because it could end up being too complicated for it to figure out which files to edit if there are multiple uses of <code>[advancefrom]</code>, and it also doesn't want to assume where to put the [[ModificationWML|[modify_unit_type]]] tag in <tt>_main.cfg</tt>.

== wmlindent ==

Call with no arguments to filter WML on standard input to reindented WML on
standard output. If arguments are specified, they are taken to be files to be
re-indented in place; a directory name causes reindenting on all WML
beneath it.

The indent unit is four spaces. Absence of an option to change this is
deliberate; the purpose of this tool is to ''prevent'' style wars, not encourage
them.

On non-empty lines, this code never modifies anything but leading and
trailing whitespace. Leading whitespace will be regularized to the
current indent; trailing whitespace will be stripped. After processing
all lines will end with a Unix-style <code>\n</code> end-of-line marker.

Runs of entirely blank lines will be reduced to one blank line, except
in two cases where they will be discarded: (a) before WML closing
tags, and (b) after WML opening tags.

It is possible to wrap a section of lines in special comments so that
<tt>wmlindent</tt> will ignore them. You may need to do this for unbalanced
macros (it's better, though, to get rid of those where possible).
Use '<code>wmlindent: {start,stop} ignoring</code>' anywhere in a comment.

It is also possible to declare custom openers an closers, e.g for macros
that are actually control constructs. To do this, use declarations

# wmlindent: opener "{EXCEPTIONAL_OPENER "
# wmlindent: closer "{EXCEPTIONAL_CLOSER "

The lines after an opener will be indented an extra level; a closer
and lines following will be indented one level less. Note that these
declare prefixes; any prefix match to the non-whitespace text of a line
will be recognized.

The public utility macros "<code>{FOREACH</code>" and "<code>{NEXT</code>" come as wired-in exceptions,
because it is not guaranteed that their indent declarations will be processed
before the macro library is reached.

Interrupting <tt>wmlindent</tt> ought to be safe, as each reindenting will be done to a copy
that is atomically renamed when it's done. If the output file is identical
to the input, the output file will simply be deleted, so the timestamp
on the input file won't be touched.

The <tt>--dryrun</tt> option detects and reports files that would be changed
without changing them. The <tt>--verbose</tt> or <tt>-v</tt> option enables reporting
of files that are (or would be, under <tt>--dryrun</tt>) changed. With <tt>-v -v</tt>,
unchanged files are also reported. The <tt>--exclude</tt> option takes a regexp
and excludes files matching it.

If you don't apply this tool to your own WML that you wish to submit, the
mainline-campaign maintainers will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML
that is syntactically unbalanced. Unbalanced double quotes that aren't part
of a multiline literal will also confuse it. You will receive warnings
if there's an indent open at end of file or if a closer occurs with
indent already zero; these two conditions strongly suggest unbalanced WML.

== GUI.pyw ==

Starting from version 1.11.15 and 1.13.0, a GUI (written in Tkinter, plus the themed widgets ttk) is available in the same directory as the other tools. To use it, you need to have a version of Python equal to or greater than 3.1.0 (the 3.0.x series doesn't include the ttk widgets, and as such is unsuitable for this script).

If you're on Linux, be sure to have installed the ''python3-tk'' module, '''or the application won't run at all'''. To install it in a Debian-based distro (like Ubuntu), type this line in a Terminal:
sudo apt install python3-tk

To start it, just double click on the GUI.pyw file. The interface is pretty much self-explanatory, and allows you to run wmllint, wmlscope, wmlindent and wmlxgettext, modify their options, select an add-on and save the tools' output as a text file.

== See Also ==
* [[Translation Maintenance Commands]] (for <tt>wmlxgettext</tt>)

[[Category:Create]]
[[Category:Tools]]

Maintenance tools

2026-07-03T16:36:21Z

Pentarctagon: /* wmllint */

<div class="floatright"> __TOC__ </div>

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These
are:

; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.

; wmllint: a utility for sanity-checking WML syntax and porting your old WML to the current version of WML.

; wmlindent: a utility for reindenting WML to a uniform style.

; GUI.pyw: a graphical interface

== General Information ==

You will need a Python 3 interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python 3 installed; for Windows it's a free download
from http://www.python.org. You will also need to know how to run command-line tools on your system.

If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.16-tools (or the convenient version).
sudo apt install wesnoth-1.16-tools

All three tools will require you to supply a directory list. This is a set of directories containing the WML files you want to work on.

This page is intended as documentation for users.

Note to Windows Users: This means you have to run it from the '''Command Line'''. The command line may be reached by hitting Start, then Run, then "cmd" or "command" depending on your version of Windows.

Example uses:
python wmllint path\to\files
python wmlindent path\to\files

Another example:
"C:\Program Files\Python3.7\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns
(You have to specify the full directory path to the executable if you don't have your environment variables set up correctly).
The first thing you type is the path to your python executable, followed by a space. The second thing you type is the path to the desired script to run, followed by a space. The third thing you type is the path to the folder (or file) to be processed.

'''A convenient way of running wmllint''' on Linux (Debian or Ubuntu) and Windows in comparison, '''Linux''':

Assuming we're working with wesnoth 1.16 or more advanced versions.
python3 /usr/share/games/wesnoth/1.16/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.16/data/core ~/.local/share/wesnoth/1.16/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
I have these commands inside of a file named
wmllint_dryrun_ASC.sh
and execute it by opening a shell (=terminal, console, command window, bash,...), navigating into the directory with that file and typing
bash wmllint_dryrun_ASC.sh
The python3 command should be automatically known on Debian. The path to the script tells the python interpreter what to execute. --dryrun: A wmllint option, see below. The path to the core files is needed to let wmllint know about e.g. defined core units, followed by the path to the add-on that shall be checked; the last two commands cause the result of the wmllint usage to be written into those files in the same directory as the script.
'''Windows''', this is logically exactly the same as the Linux shell script above, so if you are on a Mac you can probably conclude how you need to adapt the paths:
E:\Python37\python.exe E:\Programme\Wesnoth_1.16_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.16_git\data\core E:\Programme\Wesnoth_1.16_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
This is the content of a .txt file, whose extension I rename to .bat and double-click onto it. Opening a command window is not needed this way.
Since Python isn't natively installed on windows and I don't have environment variables set, the full path to python.exe is given. If your directories contain spaces it may help to include the path in quotes:
"C:\Programs\Battle for Wesnoth 1.16\data\tools\wmllint"
Remember that you do not need to enter all of the commands/paths at once. If it doesn't work, start with only "python" or "C:\Python37\python.exe" or the like and interpret the error messages that you get. If you get an "unknown command", python isn't installed or environment variables aren't set correctly. After that, you can add the later commands one by one.

== wmlscope ==

The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic (see [https://github.com/wesnoth/wesnoth/issues/5332 issue 5332] for more info). They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.

<tt>wmlscope</tt> also checks macro invocations for consistency. It will complain
if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

<table class="wikitable"><tr>
<th>Type</th>
<th>Meaning</th>
<th>Formals requiring this type</th>
<th>Literals of this type</th>
</tr>
<tr>
<td>side</td>
<td>a single side number</td>
<td>SIDE, *_SIDE, SIDE[0-9]</td>
<td>a numeric or "global"</td>
</tr>
<tr>
<td>numeric</td>
<td>a numeric integer literal</td>
<td>SIDE, X, Y, RED, GREEN, BLUE, TURN, PROB, LAYER, TIME, *_SIDE, *NUMBER, *AMOUNT, *COST, *RADIUS, *_X, *_Y, *_INCREMENT, *_FACTOR, *_TIME, *_SIZE, DURATION</td>
<td>\-?[0-9]+</td>
</tr>
<tr>
<td>percentage</td>
<td>a percentage</td>
<td>*PERCENTAGE</td>
<td>a numeric or 0\.[0-9]+</td>
</tr>
<tr>
<td>position</td>
<td>a single x,y coordinate</td>
<td>POSITION, *_POSITION, BASE</td>
<td>-?[0-9]+,-?[0-9]+</td>
</tr>
<tr>
<td>span</td>
<td>a set of coordinates or coordinate ranges</td>
<td>*_SPAN</td>
<td>a numeric, position or ([0-9]+\-[0-9]+,?|[0-9]+,?)+</td>
</tr>
<tr>
<td>alliance</td>
<td>a set of side numbers</td>
<td>SIDES, *_SIDES</td>
<td>a span, or the empty string</td>
</tr>
<tr>
<td>range</td>
<td>an attack range</td>
<td>RANGE</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>alignment</td>
<td>an alignment keyword</td>
<td>ALIGN</td>
<td>"lawful" or "neutral" or "chaotic"</td>
</tr>
<tr>
<td>types</td>
<td>a set of unit types</td>
<td>TYPES</td>
<td>a shortname, name, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>terrain_pattern</td>
<td>a set of terrain codes to filter</td>
<td>ADJACENT*, TERRAINLIST*, *TERRAIN_PATTERN, RESTRICTING</td>
<td>a terrain_code or name</td>
</tr>
<tr>
<td>terrain_code</td>
<td>a single terrain code, perhaps with overlay</td>
<td>TERRAIN*, *TERRAIN</td>
<td>a shortname or (\*|[A-Z][a-z]+)\^([A-Z][a-z\\|/]+\Z)?</td>
</tr>
<tr>
<td>shortname</td>
<td>a terrain code or a short, capitalized variable name</td>
<td></td>
<td>[A-Z][a-z][a-z]?</td>
<tr>
<td>name</td>
<td>a name or identifier</td>
<td>NAME, VAR, IMAGESTEM, ID, FLAG, *_NAME, *_ID, NAMESPACE, BUILDER, *_VAR</td>
<td>anything without spaces that matches no other type</td>
</tr>
<tr>
<td>optional_string</td>
<td>a string value (may be empty)</td>
<td>ID_STRING, NAME_STRING, DESCRIPTION, IPF</td>
<td>a string, or the empty string</td>
</tr>
<tr>
<td>string</td>
<td>a nonempty string not matching any of the preceding types</td>
<td>STRING, TYPE, TEXT, *_STRING, *_TYPE, *_TEXT</td>
<td>a shortname, a name, a stringliteral, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>stringliteral</td>
<td>a string in doublequotes or a translated string</td>
<td></td>
<td>".*" or _.* but not _[a-z].*</td>
</tr>
<tr>
<td>image</td>
<td>an image path, perhaps with [[ImagePathFunctionWML|image path functions]]</td>
<td>*IMAGE, PROFILE</td>
<td>[A-Za-z0-9{}.][A-Za-z0-9_/+{}.-]*\.(png|jpg)(?=(~.*)?)</td>
</tr>
<tr>
<td>sound</td>
<td>a music or sound filename</td>
<td>MUSIC, SOUND</td>
<td>string ending with ".wav" or ".ogg"</td>
</tr>
<tr>
<td>filter</td>
<td>[[FilterWML|WML filter]]</td>
<td>FILTER</td>
<td>any non-quoted string containing "="</td>
</tr>
<tr>
<td>WML</td>
<td>arbitrary WML fragment</td>
<td>WML, *_WML</td>
<td>any non-quoted string containing "=", or the empty string</td>
</tr>
<tr>
<td>affix</td>
<td>a prefix, suffix, or infix for a variable name</td>
<td>AFFIX, *AFFIX, POSTFIX, ROTATION</td>
<td>a shortname or name, or the empty string</td>
</tr>
<tr>
<td>any</td>
<td>anything</td>
<td>*VALUE, [ARS][0-9]</td>
<td>anything</td>
</tr>
</table>

If the actual argument is a macro call {.*}, then it matches any formal. Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in data/tools/Makefile of the source distribution. Here are some of those reports:

; make unresolved: Report on unresolved macro calls and resource references; also report macro argument-type mismatches. (This is what you are most likely to want to do).

; make all: Report all macro and resource file references, not just unresolved ones.

; make collisions: Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand
[http://docs.python.org/lib/re-syntax.html Python regular expressions].

; -h, --help: Emit a help message and quit
; -c, --crossreference: Report resolved macro references (implies <tt>-w 1</tt>)
; -C, --collisions: Report duplicate resource files
; -d, --deflist: Make definition list. (This one is for campaign server maintainers.)
; -e regexp, --exclude regexp: Ignore files matching the specified regular expression.
; -f dir, --from dir: Report only on macros defined under dir
; -l, --listfiles: List files that will be processed
; -r ddd, --refcount=ddd: Report only on macros with references in exactly ddd files.
; -t TYPELIST, --typelist TYPELIST: List actual & formal argtypes for calls in fname
; -u, --unresolved: Report unresolved macro references
; -w, --warnlevel: Set to 1 to warn of duplicate macro definitions
; -p, --progress: Show progress
; --force-used reg: Ignore reference count 0 on names matching regexp
; --extracthelp: Extract help from macro definition comments.
; --unchecked: Report all macros with untyped formals.
; --version: show program's version number and exit

These options are used with a list of directories as arguments; if none is given,
<tt>wmlscope</tt> behaves as though the current directory had been specified as a
single argument. Each directory is treated as a separate domain for
macro and resource visibility purposes.

<tt>wmlscope</tt> recognizes two kinds of namespace, exporting and non-exporting.
Exporting namespaces make all their resources and macro names
globally visible. You can make a namespace exporting by embedding
a comment like this in it:

# wmlscope: export=yes

Wesnoth core data is an exporting namespace. Campaigns are non-exporting;
they should contain the declaration

# wmlscope: export=no

somewhere. <tt>wmlscope</tt> will complain when it sees a namespace with no export
property, then treat it as non-exporting.

You can tell <tt>wmlscope</tt> to ignore stretches of config files
with the following magic comments:

# wmlscope: start ignoring
# wmlscope: stop ignoring

Similarly, you can tell <tt>wmlscope</tt> to ignore multiple or duplicate macro
definitions in a range of lines with the following magic comments:

# wmlscope: start conditionals
# wmlscope: stop conditionals

The following magic comment:

# wmlscope: prune FOOBAR

will cause <tt>wmlscope</tt> to forget about all but one of the definitions of
<tt>FOOBAR</tt> it has seen. This will be useful mainly for symbols that have
different definitions enabled by an <tt>#ifdef</tt>.

Due to a preprocessor limitation, inline macros cannot contain a documentation
string. If you need to document these macros in the HTML macro reference, you
can use the following directive:

# wmlscope: docstring FOOBAR

The docstring for the FOOBAR macro will be collected until a non-comment line,
a <tt>#define</tt> or another <tt># wmlscope: docstring</tt> are found. External
docstrings '''''must''''' be defined before the macro to which they refer; defining
two or more external docstrings keeps only the most recent one, but having both an
external and an internal docstring is allowed (in this case, the internal one
will be appended to the external one in the macro reference).

This tool does catch one kind of implicit reference: if an attack name
is specified but no icon is given, the attack icon will default to
a name generated from the attack name. This behavior can be suppressed
by adding a magic comment containing the string "no-icon" to the <tt>name=</tt>
line.

The checking done by this tool has a couple of flaws:

(1) It doesn't actually evaluate file inclusions. Instead, any
macro definition satisfies any macro call made under the same
directory. Exception: when an <tt>#undef</tt> is detected, the macro is
tagged local and not visible outside the span of lines where it was
defined.

(2) It doesn't read <tt>[binary_path]</tt> tags, as this would require
implementing a WML parser. Instead, it assumes that a resource-file
reference can be satisfied by any matching image file from anywhere
in the same directory it came from. The resources under the '''''first'''''
directory argument (only) are visible everywhere.

(3) A reference with embedded {}s in a macro will have the macro's
formal args substituted in at WML evaluation time. Instead, this
tool treats each {} as a .* wildcard and considers the reference to
match '''''every''''' resource filename that matches that pattern.
Under appropriate circumstances this might report a resource filename
statically matching the pattern as having been referenced even
though none of the actual macro calls would actually generate it.

Problems (1) and (2) imply that this tool might conceivably report
that a reference has been satisfied when under actual
WML-interpreter rules it has not.

The reporting format is compatible with GNU Emacs compile mode.

For debugging purposes, an in-line comment of the form

# wmlscope: warnlevel NNN

sets the warning level.

== wmllint ==

<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:

* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.

* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. If you port such old code, use <tt>wmllint-1.4</tt>, which is located in the same directory as <tt>wmllint</tt>. It will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

<tt>wmllint</tt> also performs various sanity-checking operations, reporting:

* unbalanced tags
* strings that need a translation mark and do not have them
* strings that have a translation mark and should not
* translatable strings containing macro references
* filter references by description= (id= in 1.5) not matched by an actual unit
* abilities or traits without matching special notes, or vice-versa
* consistency between recruit= and recruitment_pattern= instances
* double space after punctuation in translatable strings.
* unknown races or movement types in units

<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

; -h, --help: Emit a help message and quit.
; -c, --clean: Clean up -bak files.
; -D, --diffs: Display diffs between converted and unconverted files.
; -d, --dryrun: List changes (-v) but don't perform them.
; -r, --revert: Revert the conversion from the -bak files.
; -m, --missing: Warn about tags without side= keys now applying to all sides.
; -s, --stripcr: Convert DOS-style CR/LF to Unix-style LF.
; -v, --verbose: Set verbosity; more details below.
; -K, --known: Suppress check for unknown unit types, recruits, races, scenarios, etc.
; --version: show program's version number and exit
; --config: allows specifying directories to include ('''include_dirs'''), directories to exclude ('''ignore_directories'''), and files to exclude ('''ignore_files''').

The verbosity option works like this:

; -v: lists changes.
; -v -v: warns of maps already converted.
; -v -v -v: names each file before it's processed.
; -v -v -v -v: shows verbose parse details (developers only).

The recommended procedure is this:

# Run it with --dryrun first to see what it will do.
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
# Eyeball the changes with the --diff option.
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
# Test the conversion.
# Use either --clean to remove the -bak files or --revert to undo the conversion.

wmllint supports a number of magic comments to customize its behaviour and avoid false positives. Almost all magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. These are all documented at the top of the wmllint tool itself: https://github.com/wesnoth/wesnoth/blob/master/data/tools/wmllint

=== Explanations of <tt>wmllint</tt> diagnostics ===
Some <tt>wmllint</tt> diagnostics may require further explanation for UMC authors to understand; this section will be for providing such explanations, and descriptions of how to solve and/or silence them.

In these, <code>%s</code> will be replaced by a string. When the recommended solution also includes a <code>%s</code>, it's a suggestion to copy the string from the error message into your code.

* <code>nonstandard word-wrap style within message</code>: This message meant there was an unexpected newline character within a <code>[message]</code> tag. However, this check was removed in the 1.15.10 release. Pre-1.15.10, add-on developers could silence by putting a <code># wmllint: display on</code> comment before the string and a <code># wmllint: display off</code> comment after the string, however, post-1.15.10, this is no longer necessary.
* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>unknown speaker '%s' of [message]</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the speaker is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is SPEAKER</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>unknown '%s' referred to by id</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the unit is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is UNIT</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>%s has unknown advancements</code> (in cases where you'd think the advancement ''would'' be known): This means the unit has an advancement that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load mainline units for checking advancements. Note that it's also possible that you just made typo, too, so be sure to check your spelling. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>.description may need hand fixup</code>: This one comes from mucking around with the <code>.description</code> field of unit data manually in a hackish fashion. There isn't really much of a way to work around it, besides just the "don't do that" solution.
* <code>tag stack nonempty (%s) at end of file.</code>: This means that you have unbalanced tags somewhere in the file, e.g. an opener without a closer, or vice versa. This can often be seen when defining macros for unit abilities. A way to fix this warning is to wrap the section with unbalanced tags with a <code># wmllint: unbalanced-on</code> magic comment beforehand and a <code># wmllint: unbalanced-off</code> magic comment afterwards. As having unbalanced tags will also cause issues for other WML maintenance tools, such as <tt>wmlindent</tt> and <tt>wmlxgettext</tt>, you may also want to add separate magic comments for each of them (see their documentation for the form they take).
* <code>unit declaration without side attribute</code>: the default side for a unit declaration when left implicit is side 1. Specify your unit sides explicitly to solve this.
* <code>no %s units recruitable at difficulty %s</code> (even when there are such units recruitable): This diagnostic has to do with matching the <code>usage</code> key of units recruitable by an AI side with their <code>recruitment_pattern</code>. It means the unit has a usage that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can know which mainline units are recruitable. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown movement type</code> (even when you'd think that that movement type ''would'' actually be known): This means the unit has a movetype that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline movement types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown race</code> (even when you'd think that that race ''would'' actually be known): This means the unit has a race that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline races. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>derivation of %s from %s does not resolve</code> (even when you'd think it would): This means that a unit using the [[UnitTypeWML#Other_tags|[base_unit]]] tag specifies a unit ID in that tag that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the core units for its derivation checks. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>[advancefrom] needs to be manually updated to [modify_unit_type] and moved into the _main.cfg file</code>: This one is pretty self-explanatory: [[UnitTypeWML#Unit_Type|[advancefrom]]] was deprecated in [https://github.com/wesnoth/wesnoth/commit/3950f40f3f0483032bc70b3e57166bd355acd9fc commit 3950f40] due to [https://github.com/wesnoth/wesnoth/issues/3955 issue #3955], and in fact doesn't even work anymore (in 1.16) as per [https://github.com/wesnoth/wesnoth/issues/6204 issue #6204]. The main reason <tt>wmllint</tt> can't fix this automatically is because it could end up being too complicated for it to figure out which files to edit if there are multiple uses of <code>[advancefrom]</code>, and it also doesn't want to assume where to put the [[ModificationWML|[modify_unit_type]]] tag in <tt>_main.cfg</tt>.

== wmlindent ==

Call with no arguments to filter WML on standard input to reindented WML on
standard output. If arguments are specified, they are taken to be files to be
re-indented in place; a directory name causes reindenting on all WML
beneath it.

The indent unit is four spaces. Absence of an option to change this is
deliberate; the purpose of this tool is to ''prevent'' style wars, not encourage
them.

On non-empty lines, this code never modifies anything but leading and
trailing whitespace. Leading whitespace will be regularized to the
current indent; trailing whitespace will be stripped. After processing
all lines will end with a Unix-style <code>\n</code> end-of-line marker.

Runs of entirely blank lines will be reduced to one blank line, except
in two cases where they will be discarded: (a) before WML closing
tags, and (b) after WML opening tags.

It is possible to wrap a section of lines in special comments so that
<tt>wmlindent</tt> will ignore them. You may need to do this for unbalanced
macros (it's better, though, to get rid of those where possible).
Use '<code>wmlindent: {start,stop} ignoring</code>' anywhere in a comment.

It is also possible to declare custom openers an closers, e.g for macros
that are actually control constructs. To do this, use declarations

# wmlindent: opener "{EXCEPTIONAL_OPENER "
# wmlindent: closer "{EXCEPTIONAL_CLOSER "

The lines after an opener will be indented an extra level; a closer
and lines following will be indented one level less. Note that these
declare prefixes; any prefix match to the non-whitespace text of a line
will be recognized.

The public utility macros "<code>{FOREACH</code>" and "<code>{NEXT</code>" come as wired-in exceptions,
because it is not guaranteed that their indent declarations will be processed
before the macro library is reached.

Interrupting <tt>wmlindent</tt> ought to be safe, as each reindenting will be done to a copy
that is atomically renamed when it's done. If the output file is identical
to the input, the output file will simply be deleted, so the timestamp
on the input file won't be touched.

The <tt>--dryrun</tt> option detects and reports files that would be changed
without changing them. The <tt>--verbose</tt> or <tt>-v</tt> option enables reporting
of files that are (or would be, under <tt>--dryrun</tt>) changed. With <tt>-v -v</tt>,
unchanged files are also reported. The <tt>--exclude</tt> option takes a regexp
and excludes files matching it.

If you don't apply this tool to your own WML that you wish to submit, the
mainline-campaign maintainers will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML
that is syntactically unbalanced. Unbalanced double quotes that aren't part
of a multiline literal will also confuse it. You will receive warnings
if there's an indent open at end of file or if a closer occurs with
indent already zero; these two conditions strongly suggest unbalanced WML.

== GUI.pyw ==

Starting from version 1.11.15 and 1.13.0, a GUI (written in Tkinter, plus the themed widgets ttk) is available in the same directory as the other tools. To use it, you need to have a version of Python equal to or greater than 3.1.0 (the 3.0.x series doesn't include the ttk widgets, and as such is unsuitable for this script).

If you're on Linux, be sure to have installed the ''python3-tk'' module, '''or the application won't run at all'''. To install it in a Debian-based distro (like Ubuntu), type this line in a Terminal:
sudo apt install python3-tk

To start it, just double click on the GUI.pyw file. The interface is pretty much self-explanatory, and allows you to run wmllint, wmlscope, wmlindent and wmlxgettext, modify their options, select an add-on and save the tools' output as a text file.

== See Also ==
* [[Translation Maintenance Commands]] (for <tt>wmlxgettext</tt>)

[[Category:Create]]
[[Category:Tools]]

Maintenance tools

2026-07-03T16:34:10Z

Pentarctagon: /* wmllint */

<div class="floatright"> __TOC__ </div>

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These
are:

; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.

; wmllint: a utility for sanity-checking WML syntax and porting your old WML to the current version of WML.

; wmlindent: a utility for reindenting WML to a uniform style.

; GUI.pyw: a graphical interface

== General Information ==

You will need a Python 3 interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python 3 installed; for Windows it's a free download
from http://www.python.org. You will also need to know how to run command-line tools on your system.

If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.16-tools (or the convenient version).
sudo apt install wesnoth-1.16-tools

All three tools will require you to supply a directory list. This is a set of directories containing the WML files you want to work on.

This page is intended as documentation for users.

Note to Windows Users: This means you have to run it from the '''Command Line'''. The command line may be reached by hitting Start, then Run, then "cmd" or "command" depending on your version of Windows.

Example uses:
python wmllint path\to\files
python wmlindent path\to\files

Another example:
"C:\Program Files\Python3.7\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns
(You have to specify the full directory path to the executable if you don't have your environment variables set up correctly).
The first thing you type is the path to your python executable, followed by a space. The second thing you type is the path to the desired script to run, followed by a space. The third thing you type is the path to the folder (or file) to be processed.

'''A convenient way of running wmllint''' on Linux (Debian or Ubuntu) and Windows in comparison, '''Linux''':

Assuming we're working with wesnoth 1.16 or more advanced versions.
python3 /usr/share/games/wesnoth/1.16/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.16/data/core ~/.local/share/wesnoth/1.16/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
I have these commands inside of a file named
wmllint_dryrun_ASC.sh
and execute it by opening a shell (=terminal, console, command window, bash,...), navigating into the directory with that file and typing
bash wmllint_dryrun_ASC.sh
The python3 command should be automatically known on Debian. The path to the script tells the python interpreter what to execute. --dryrun: A wmllint option, see below. The path to the core files is needed to let wmllint know about e.g. defined core units, followed by the path to the add-on that shall be checked; the last two commands cause the result of the wmllint usage to be written into those files in the same directory as the script.
'''Windows''', this is logically exactly the same as the Linux shell script above, so if you are on a Mac you can probably conclude how you need to adapt the paths:
E:\Python37\python.exe E:\Programme\Wesnoth_1.16_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.16_git\data\core E:\Programme\Wesnoth_1.16_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
This is the content of a .txt file, whose extension I rename to .bat and double-click onto it. Opening a command window is not needed this way.
Since Python isn't natively installed on windows and I don't have environment variables set, the full path to python.exe is given. If your directories contain spaces it may help to include the path in quotes:
"C:\Programs\Battle for Wesnoth 1.16\data\tools\wmllint"
Remember that you do not need to enter all of the commands/paths at once. If it doesn't work, start with only "python" or "C:\Python37\python.exe" or the like and interpret the error messages that you get. If you get an "unknown command", python isn't installed or environment variables aren't set correctly. After that, you can add the later commands one by one.

== wmlscope ==

The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic (see [https://github.com/wesnoth/wesnoth/issues/5332 issue 5332] for more info). They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.

<tt>wmlscope</tt> also checks macro invocations for consistency. It will complain
if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

<table class="wikitable"><tr>
<th>Type</th>
<th>Meaning</th>
<th>Formals requiring this type</th>
<th>Literals of this type</th>
</tr>
<tr>
<td>side</td>
<td>a single side number</td>
<td>SIDE, *_SIDE, SIDE[0-9]</td>
<td>a numeric or "global"</td>
</tr>
<tr>
<td>numeric</td>
<td>a numeric integer literal</td>
<td>SIDE, X, Y, RED, GREEN, BLUE, TURN, PROB, LAYER, TIME, *_SIDE, *NUMBER, *AMOUNT, *COST, *RADIUS, *_X, *_Y, *_INCREMENT, *_FACTOR, *_TIME, *_SIZE, DURATION</td>
<td>\-?[0-9]+</td>
</tr>
<tr>
<td>percentage</td>
<td>a percentage</td>
<td>*PERCENTAGE</td>
<td>a numeric or 0\.[0-9]+</td>
</tr>
<tr>
<td>position</td>
<td>a single x,y coordinate</td>
<td>POSITION, *_POSITION, BASE</td>
<td>-?[0-9]+,-?[0-9]+</td>
</tr>
<tr>
<td>span</td>
<td>a set of coordinates or coordinate ranges</td>
<td>*_SPAN</td>
<td>a numeric, position or ([0-9]+\-[0-9]+,?|[0-9]+,?)+</td>
</tr>
<tr>
<td>alliance</td>
<td>a set of side numbers</td>
<td>SIDES, *_SIDES</td>
<td>a span, or the empty string</td>
</tr>
<tr>
<td>range</td>
<td>an attack range</td>
<td>RANGE</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>alignment</td>
<td>an alignment keyword</td>
<td>ALIGN</td>
<td>"lawful" or "neutral" or "chaotic"</td>
</tr>
<tr>
<td>types</td>
<td>a set of unit types</td>
<td>TYPES</td>
<td>a shortname, name, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>terrain_pattern</td>
<td>a set of terrain codes to filter</td>
<td>ADJACENT*, TERRAINLIST*, *TERRAIN_PATTERN, RESTRICTING</td>
<td>a terrain_code or name</td>
</tr>
<tr>
<td>terrain_code</td>
<td>a single terrain code, perhaps with overlay</td>
<td>TERRAIN*, *TERRAIN</td>
<td>a shortname or (\*|[A-Z][a-z]+)\^([A-Z][a-z\\|/]+\Z)?</td>
</tr>
<tr>
<td>shortname</td>
<td>a terrain code or a short, capitalized variable name</td>
<td></td>
<td>[A-Z][a-z][a-z]?</td>
<tr>
<td>name</td>
<td>a name or identifier</td>
<td>NAME, VAR, IMAGESTEM, ID, FLAG, *_NAME, *_ID, NAMESPACE, BUILDER, *_VAR</td>
<td>anything without spaces that matches no other type</td>
</tr>
<tr>
<td>optional_string</td>
<td>a string value (may be empty)</td>
<td>ID_STRING, NAME_STRING, DESCRIPTION, IPF</td>
<td>a string, or the empty string</td>
</tr>
<tr>
<td>string</td>
<td>a nonempty string not matching any of the preceding types</td>
<td>STRING, TYPE, TEXT, *_STRING, *_TYPE, *_TEXT</td>
<td>a shortname, a name, a stringliteral, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>stringliteral</td>
<td>a string in doublequotes or a translated string</td>
<td></td>
<td>".*" or _.* but not _[a-z].*</td>
</tr>
<tr>
<td>image</td>
<td>an image path, perhaps with [[ImagePathFunctionWML|image path functions]]</td>
<td>*IMAGE, PROFILE</td>
<td>[A-Za-z0-9{}.][A-Za-z0-9_/+{}.-]*\.(png|jpg)(?=(~.*)?)</td>
</tr>
<tr>
<td>sound</td>
<td>a music or sound filename</td>
<td>MUSIC, SOUND</td>
<td>string ending with ".wav" or ".ogg"</td>
</tr>
<tr>
<td>filter</td>
<td>[[FilterWML|WML filter]]</td>
<td>FILTER</td>
<td>any non-quoted string containing "="</td>
</tr>
<tr>
<td>WML</td>
<td>arbitrary WML fragment</td>
<td>WML, *_WML</td>
<td>any non-quoted string containing "=", or the empty string</td>
</tr>
<tr>
<td>affix</td>
<td>a prefix, suffix, or infix for a variable name</td>
<td>AFFIX, *AFFIX, POSTFIX, ROTATION</td>
<td>a shortname or name, or the empty string</td>
</tr>
<tr>
<td>any</td>
<td>anything</td>
<td>*VALUE, [ARS][0-9]</td>
<td>anything</td>
</tr>
</table>

If the actual argument is a macro call {.*}, then it matches any formal. Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in data/tools/Makefile of the source distribution. Here are some of those reports:

; make unresolved: Report on unresolved macro calls and resource references; also report macro argument-type mismatches. (This is what you are most likely to want to do).

; make all: Report all macro and resource file references, not just unresolved ones.

; make collisions: Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand
[http://docs.python.org/lib/re-syntax.html Python regular expressions].

; -h, --help: Emit a help message and quit
; -c, --crossreference: Report resolved macro references (implies <tt>-w 1</tt>)
; -C, --collisions: Report duplicate resource files
; -d, --deflist: Make definition list. (This one is for campaign server maintainers.)
; -e regexp, --exclude regexp: Ignore files matching the specified regular expression.
; -f dir, --from dir: Report only on macros defined under dir
; -l, --listfiles: List files that will be processed
; -r ddd, --refcount=ddd: Report only on macros with references in exactly ddd files.
; -t TYPELIST, --typelist TYPELIST: List actual & formal argtypes for calls in fname
; -u, --unresolved: Report unresolved macro references
; -w, --warnlevel: Set to 1 to warn of duplicate macro definitions
; -p, --progress: Show progress
; --force-used reg: Ignore reference count 0 on names matching regexp
; --extracthelp: Extract help from macro definition comments.
; --unchecked: Report all macros with untyped formals.
; --version: show program's version number and exit

These options are used with a list of directories as arguments; if none is given,
<tt>wmlscope</tt> behaves as though the current directory had been specified as a
single argument. Each directory is treated as a separate domain for
macro and resource visibility purposes.

<tt>wmlscope</tt> recognizes two kinds of namespace, exporting and non-exporting.
Exporting namespaces make all their resources and macro names
globally visible. You can make a namespace exporting by embedding
a comment like this in it:

# wmlscope: export=yes

Wesnoth core data is an exporting namespace. Campaigns are non-exporting;
they should contain the declaration

# wmlscope: export=no

somewhere. <tt>wmlscope</tt> will complain when it sees a namespace with no export
property, then treat it as non-exporting.

You can tell <tt>wmlscope</tt> to ignore stretches of config files
with the following magic comments:

# wmlscope: start ignoring
# wmlscope: stop ignoring

Similarly, you can tell <tt>wmlscope</tt> to ignore multiple or duplicate macro
definitions in a range of lines with the following magic comments:

# wmlscope: start conditionals
# wmlscope: stop conditionals

The following magic comment:

# wmlscope: prune FOOBAR

will cause <tt>wmlscope</tt> to forget about all but one of the definitions of
<tt>FOOBAR</tt> it has seen. This will be useful mainly for symbols that have
different definitions enabled by an <tt>#ifdef</tt>.

Due to a preprocessor limitation, inline macros cannot contain a documentation
string. If you need to document these macros in the HTML macro reference, you
can use the following directive:

# wmlscope: docstring FOOBAR

The docstring for the FOOBAR macro will be collected until a non-comment line,
a <tt>#define</tt> or another <tt># wmlscope: docstring</tt> are found. External
docstrings '''''must''''' be defined before the macro to which they refer; defining
two or more external docstrings keeps only the most recent one, but having both an
external and an internal docstring is allowed (in this case, the internal one
will be appended to the external one in the macro reference).

This tool does catch one kind of implicit reference: if an attack name
is specified but no icon is given, the attack icon will default to
a name generated from the attack name. This behavior can be suppressed
by adding a magic comment containing the string "no-icon" to the <tt>name=</tt>
line.

The checking done by this tool has a couple of flaws:

(1) It doesn't actually evaluate file inclusions. Instead, any
macro definition satisfies any macro call made under the same
directory. Exception: when an <tt>#undef</tt> is detected, the macro is
tagged local and not visible outside the span of lines where it was
defined.

(2) It doesn't read <tt>[binary_path]</tt> tags, as this would require
implementing a WML parser. Instead, it assumes that a resource-file
reference can be satisfied by any matching image file from anywhere
in the same directory it came from. The resources under the '''''first'''''
directory argument (only) are visible everywhere.

(3) A reference with embedded {}s in a macro will have the macro's
formal args substituted in at WML evaluation time. Instead, this
tool treats each {} as a .* wildcard and considers the reference to
match '''''every''''' resource filename that matches that pattern.
Under appropriate circumstances this might report a resource filename
statically matching the pattern as having been referenced even
though none of the actual macro calls would actually generate it.

Problems (1) and (2) imply that this tool might conceivably report
that a reference has been satisfied when under actual
WML-interpreter rules it has not.

The reporting format is compatible with GNU Emacs compile mode.

For debugging purposes, an in-line comment of the form

# wmlscope: warnlevel NNN

sets the warning level.

== wmllint ==

<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:

* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.

* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. If you port such old code, use <tt>wmllint-1.4</tt>, which is located in the same directory as <tt>wmllint</tt>. It will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

<tt>wmllint</tt> also performs various sanity-checking operations, reporting:

* unbalanced tags
* strings that need a translation mark and do not have them
* strings that have a translation mark and should not
* translatable strings containing macro references
* filter references by description= (id= in 1.5) not matched by an actual unit
* abilities or traits without matching special notes, or vice-versa
* consistency between recruit= and recruitment_pattern= instances
* double space after punctuation in translatable strings.
* unknown races or movement types in units

<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

; -h, --help: Emit a help message and quit.
; -c, --clean: Clean up -bak files.
; -D, --diffs: Display diffs between converted and unconverted files.
; -d, --dryrun: List changes (-v) but don't perform them.
; -r, --revert: Revert the conversion from the -bak files.
; -m, --missing: Warn about tags without side= keys now applying to all sides.
; -s, --stripcr: Convert DOS-style CR/LF to Unix-style LF.
; -v, --verbose: Set verbosity; more details below.
; -K, --known: Suppress check for unknown unit types, recruits, races, scenarios, etc.
; --version: show program's version number and exit
; --config: allows specifying directories to include ('''include_dirs'''), directories to exclude ('''ignore_directories'''), and files to exclude ('''ignore_files''').

The verbosity option works like this:

; -v: lists changes.
; -v -v: warns of maps already converted.
; -v -v -v: names each file before it's processed.
; -v -v -v -v: shows verbose parse details (developers only).

The recommended procedure is this:

# Run it with --dryrun first to see what it will do.
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
# Eyeball the changes with the --diff option.
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
# Test the conversion.
# Use either --clean to remove the -bak files or --revert to undo the conversion.

wmllint supports a number of magic comments to customize its behaviour and avoid false positives. All magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. In the below explanations, a string of the form <code>[a|b]</code> means you may use either <code>a</code> or <code>b</code> at that location, while a string of the form <code><arg></code> indicates free text substitution.

* <code>ignore</code>: Disables checking of terrains and translation marks on the current line only.
* <code>noconvert</code>: Disables conversion of terrains and image/sound filenames on the current line only.
* <code>markcheck [on|off]</code>: Enables or disables translation mark checking from the current (next?) line onward.
* <code>no-icon</code>: If an attack has no description, without this wmllint adds a dummy description to the attack which is just the name of the attack. With this, this description insertion is suppressed.
* <code>recognize <name></code>: Indicates that the character with the given name exists even though a declaration (ie a <code>[unit]</code> or <code>[side]</code> tag) is not visible.
* <code>whofield <macro> <number></code>: Indicates that the specified macro declares a character whose name is given by the specified argument to the macro.
* <code>whofield clear <macro></code>: Removes the <code>whofield</code> definition for the specified macro.
* <code>who <macro> is <name> <name> ...</code>: Indicates that the specified macro declares one or more characters whose names are given as a space-separated list. This can also be used for macros that auto-recall a list of characters, some of which join later or may die at some point. If a definition for the macro already exists, then the specified names are appended to it. If a name is preceded by a double minus (<code>-- <name></code>) then it is removed from the definition.
* <code>unwho all|<name></code>: Removes the <code>who</code> definition for the specified macro, or all <code>who</code> definitions.
* <code>usage of "<unit>" is <class></code>: Declares the usage of the specified unit (the <code>usage=</code> key in the <code>[unit_type]</code> tag). Useful if you are using macros to generate several similar unit types.
* <code>usagetype <class></code>: Declares a valid usage type for units. <code>usagetypes</code> is also recognized, and a comma-separated list of usage types can be specified.
* <code>validate-[on|off]</code>: Enables or disables stack-based validation checks. Use when you have unbalanced tags in macros.
* <code>unbalanced-[on|off]</code>: Similar to above, the precise difference is unclear.
* <code>no translatables</code>: Suppresses warnings about a missing textdomain declaration in the current file. Make sure the file really does have no translatable strings!
* <code>display [on|off]</code>: Enable or disable warnings about newlines in messages.
* <code>notecheck [on|off]</code>: Enable or disable note consistency checks for unit descriptions.
* <code>deathcheck [on|off]</code>: Enable or disable the check for units speaking in their death events.
* <code>[general|directory|local] spellings <word> <word> ...</code>: Declares the specified space-separated list of words to be valid spellings in the specified context. The context <code>local</code> indicates the current file only, while <code>directory</code> means the current file and any siblings in the same directory or subdirectories. The <code>global</code> context indicates the spellings are valid anywhere.
* <code>no spellcheck</code>: Disables spell checking on the current line.
* <code>skip-side</code>: Indicates that there is a missing side declaration at this location that will be provided by a macro expansion.
* <code>match <string> with <notes_macro></code>: Indicates that uses of the specified string in a unit definition (usually a macro, including the curly braces) should be matched up with the specified special notes macro (which is also specified as the full macro with curly braces).
* <code>no ellipsecheck</code>: Disables checking of unit ellipses on the current line.

=== Explanations of <tt>wmllint</tt> diagnostics ===
Some <tt>wmllint</tt> diagnostics may require further explanation for UMC authors to understand; this section will be for providing such explanations, and descriptions of how to solve and/or silence them.

In these, <code>%s</code> will be replaced by a string. When the recommended solution also includes a <code>%s</code>, it's a suggestion to copy the string from the error message into your code.

* <code>nonstandard word-wrap style within message</code>: This message meant there was an unexpected newline character within a <code>[message]</code> tag. However, this check was removed in the 1.15.10 release. Pre-1.15.10, add-on developers could silence by putting a <code># wmllint: display on</code> comment before the string and a <code># wmllint: display off</code> comment after the string, however, post-1.15.10, this is no longer necessary.
* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>unknown speaker '%s' of [message]</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the speaker is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is SPEAKER</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>unknown '%s' referred to by id</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the unit is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is UNIT</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>%s has unknown advancements</code> (in cases where you'd think the advancement ''would'' be known): This means the unit has an advancement that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load mainline units for checking advancements. Note that it's also possible that you just made typo, too, so be sure to check your spelling. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>.description may need hand fixup</code>: This one comes from mucking around with the <code>.description</code> field of unit data manually in a hackish fashion. There isn't really much of a way to work around it, besides just the "don't do that" solution.
* <code>tag stack nonempty (%s) at end of file.</code>: This means that you have unbalanced tags somewhere in the file, e.g. an opener without a closer, or vice versa. This can often be seen when defining macros for unit abilities. A way to fix this warning is to wrap the section with unbalanced tags with a <code># wmllint: unbalanced-on</code> magic comment beforehand and a <code># wmllint: unbalanced-off</code> magic comment afterwards. As having unbalanced tags will also cause issues for other WML maintenance tools, such as <tt>wmlindent</tt> and <tt>wmlxgettext</tt>, you may also want to add separate magic comments for each of them (see their documentation for the form they take).
* <code>unit declaration without side attribute</code>: the default side for a unit declaration when left implicit is side 1. Specify your unit sides explicitly to solve this.
* <code>no %s units recruitable at difficulty %s</code> (even when there are such units recruitable): This diagnostic has to do with matching the <code>usage</code> key of units recruitable by an AI side with their <code>recruitment_pattern</code>. It means the unit has a usage that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can know which mainline units are recruitable. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown movement type</code> (even when you'd think that that movement type ''would'' actually be known): This means the unit has a movetype that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline movement types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown race</code> (even when you'd think that that race ''would'' actually be known): This means the unit has a race that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline races. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>derivation of %s from %s does not resolve</code> (even when you'd think it would): This means that a unit using the [[UnitTypeWML#Other_tags|[base_unit]]] tag specifies a unit ID in that tag that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the core units for its derivation checks. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>[advancefrom] needs to be manually updated to [modify_unit_type] and moved into the _main.cfg file</code>: This one is pretty self-explanatory: [[UnitTypeWML#Unit_Type|[advancefrom]]] was deprecated in [https://github.com/wesnoth/wesnoth/commit/3950f40f3f0483032bc70b3e57166bd355acd9fc commit 3950f40] due to [https://github.com/wesnoth/wesnoth/issues/3955 issue #3955], and in fact doesn't even work anymore (in 1.16) as per [https://github.com/wesnoth/wesnoth/issues/6204 issue #6204]. The main reason <tt>wmllint</tt> can't fix this automatically is because it could end up being too complicated for it to figure out which files to edit if there are multiple uses of <code>[advancefrom]</code>, and it also doesn't want to assume where to put the [[ModificationWML|[modify_unit_type]]] tag in <tt>_main.cfg</tt>.

== wmlindent ==

Call with no arguments to filter WML on standard input to reindented WML on
standard output. If arguments are specified, they are taken to be files to be
re-indented in place; a directory name causes reindenting on all WML
beneath it.

The indent unit is four spaces. Absence of an option to change this is
deliberate; the purpose of this tool is to ''prevent'' style wars, not encourage
them.

On non-empty lines, this code never modifies anything but leading and
trailing whitespace. Leading whitespace will be regularized to the
current indent; trailing whitespace will be stripped. After processing
all lines will end with a Unix-style <code>\n</code> end-of-line marker.

Runs of entirely blank lines will be reduced to one blank line, except
in two cases where they will be discarded: (a) before WML closing
tags, and (b) after WML opening tags.

It is possible to wrap a section of lines in special comments so that
<tt>wmlindent</tt> will ignore them. You may need to do this for unbalanced
macros (it's better, though, to get rid of those where possible).
Use '<code>wmlindent: {start,stop} ignoring</code>' anywhere in a comment.

It is also possible to declare custom openers an closers, e.g for macros
that are actually control constructs. To do this, use declarations

# wmlindent: opener "{EXCEPTIONAL_OPENER "
# wmlindent: closer "{EXCEPTIONAL_CLOSER "

The lines after an opener will be indented an extra level; a closer
and lines following will be indented one level less. Note that these
declare prefixes; any prefix match to the non-whitespace text of a line
will be recognized.

The public utility macros "<code>{FOREACH</code>" and "<code>{NEXT</code>" come as wired-in exceptions,
because it is not guaranteed that their indent declarations will be processed
before the macro library is reached.

Interrupting <tt>wmlindent</tt> ought to be safe, as each reindenting will be done to a copy
that is atomically renamed when it's done. If the output file is identical
to the input, the output file will simply be deleted, so the timestamp
on the input file won't be touched.

The <tt>--dryrun</tt> option detects and reports files that would be changed
without changing them. The <tt>--verbose</tt> or <tt>-v</tt> option enables reporting
of files that are (or would be, under <tt>--dryrun</tt>) changed. With <tt>-v -v</tt>,
unchanged files are also reported. The <tt>--exclude</tt> option takes a regexp
and excludes files matching it.

If you don't apply this tool to your own WML that you wish to submit, the
mainline-campaign maintainers will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML
that is syntactically unbalanced. Unbalanced double quotes that aren't part
of a multiline literal will also confuse it. You will receive warnings
if there's an indent open at end of file or if a closer occurs with
indent already zero; these two conditions strongly suggest unbalanced WML.

== GUI.pyw ==

Starting from version 1.11.15 and 1.13.0, a GUI (written in Tkinter, plus the themed widgets ttk) is available in the same directory as the other tools. To use it, you need to have a version of Python equal to or greater than 3.1.0 (the 3.0.x series doesn't include the ttk widgets, and as such is unsuitable for this script).

If you're on Linux, be sure to have installed the ''python3-tk'' module, '''or the application won't run at all'''. To install it in a Debian-based distro (like Ubuntu), type this line in a Terminal:
sudo apt install python3-tk

To start it, just double click on the GUI.pyw file. The interface is pretty much self-explanatory, and allows you to run wmllint, wmlscope, wmlindent and wmlxgettext, modify their options, select an add-on and save the tools' output as a text file.

== See Also ==
* [[Translation Maintenance Commands]] (for <tt>wmlxgettext</tt>)

[[Category:Create]]
[[Category:Tools]]

Maintenance tools

2026-07-03T16:33:25Z

Pentarctagon: /* wmllint */

<div class="floatright"> __TOC__ </div>

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These
are:

; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.

; wmllint: a utility for sanity-checking WML syntax and porting your old WML to the current version of WML.

; wmlindent: a utility for reindenting WML to a uniform style.

; GUI.pyw: a graphical interface

== General Information ==

You will need a Python 3 interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python 3 installed; for Windows it's a free download
from http://www.python.org. You will also need to know how to run command-line tools on your system.

If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.16-tools (or the convenient version).
sudo apt install wesnoth-1.16-tools

All three tools will require you to supply a directory list. This is a set of directories containing the WML files you want to work on.

This page is intended as documentation for users.

Note to Windows Users: This means you have to run it from the '''Command Line'''. The command line may be reached by hitting Start, then Run, then "cmd" or "command" depending on your version of Windows.

Example uses:
python wmllint path\to\files
python wmlindent path\to\files

Another example:
"C:\Program Files\Python3.7\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns
(You have to specify the full directory path to the executable if you don't have your environment variables set up correctly).
The first thing you type is the path to your python executable, followed by a space. The second thing you type is the path to the desired script to run, followed by a space. The third thing you type is the path to the folder (or file) to be processed.

'''A convenient way of running wmllint''' on Linux (Debian or Ubuntu) and Windows in comparison, '''Linux''':

Assuming we're working with wesnoth 1.16 or more advanced versions.
python3 /usr/share/games/wesnoth/1.16/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.16/data/core ~/.local/share/wesnoth/1.16/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
I have these commands inside of a file named
wmllint_dryrun_ASC.sh
and execute it by opening a shell (=terminal, console, command window, bash,...), navigating into the directory with that file and typing
bash wmllint_dryrun_ASC.sh
The python3 command should be automatically known on Debian. The path to the script tells the python interpreter what to execute. --dryrun: A wmllint option, see below. The path to the core files is needed to let wmllint know about e.g. defined core units, followed by the path to the add-on that shall be checked; the last two commands cause the result of the wmllint usage to be written into those files in the same directory as the script.
'''Windows''', this is logically exactly the same as the Linux shell script above, so if you are on a Mac you can probably conclude how you need to adapt the paths:
E:\Python37\python.exe E:\Programme\Wesnoth_1.16_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.16_git\data\core E:\Programme\Wesnoth_1.16_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
This is the content of a .txt file, whose extension I rename to .bat and double-click onto it. Opening a command window is not needed this way.
Since Python isn't natively installed on windows and I don't have environment variables set, the full path to python.exe is given. If your directories contain spaces it may help to include the path in quotes:
"C:\Programs\Battle for Wesnoth 1.16\data\tools\wmllint"
Remember that you do not need to enter all of the commands/paths at once. If it doesn't work, start with only "python" or "C:\Python37\python.exe" or the like and interpret the error messages that you get. If you get an "unknown command", python isn't installed or environment variables aren't set correctly. After that, you can add the later commands one by one.

== wmlscope ==

The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic (see [https://github.com/wesnoth/wesnoth/issues/5332 issue 5332] for more info). They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.

<tt>wmlscope</tt> also checks macro invocations for consistency. It will complain
if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

<table class="wikitable"><tr>
<th>Type</th>
<th>Meaning</th>
<th>Formals requiring this type</th>
<th>Literals of this type</th>
</tr>
<tr>
<td>side</td>
<td>a single side number</td>
<td>SIDE, *_SIDE, SIDE[0-9]</td>
<td>a numeric or "global"</td>
</tr>
<tr>
<td>numeric</td>
<td>a numeric integer literal</td>
<td>SIDE, X, Y, RED, GREEN, BLUE, TURN, PROB, LAYER, TIME, *_SIDE, *NUMBER, *AMOUNT, *COST, *RADIUS, *_X, *_Y, *_INCREMENT, *_FACTOR, *_TIME, *_SIZE, DURATION</td>
<td>\-?[0-9]+</td>
</tr>
<tr>
<td>percentage</td>
<td>a percentage</td>
<td>*PERCENTAGE</td>
<td>a numeric or 0\.[0-9]+</td>
</tr>
<tr>
<td>position</td>
<td>a single x,y coordinate</td>
<td>POSITION, *_POSITION, BASE</td>
<td>-?[0-9]+,-?[0-9]+</td>
</tr>
<tr>
<td>span</td>
<td>a set of coordinates or coordinate ranges</td>
<td>*_SPAN</td>
<td>a numeric, position or ([0-9]+\-[0-9]+,?|[0-9]+,?)+</td>
</tr>
<tr>
<td>alliance</td>
<td>a set of side numbers</td>
<td>SIDES, *_SIDES</td>
<td>a span, or the empty string</td>
</tr>
<tr>
<td>range</td>
<td>an attack range</td>
<td>RANGE</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>alignment</td>
<td>an alignment keyword</td>
<td>ALIGN</td>
<td>"lawful" or "neutral" or "chaotic"</td>
</tr>
<tr>
<td>types</td>
<td>a set of unit types</td>
<td>TYPES</td>
<td>a shortname, name, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>terrain_pattern</td>
<td>a set of terrain codes to filter</td>
<td>ADJACENT*, TERRAINLIST*, *TERRAIN_PATTERN, RESTRICTING</td>
<td>a terrain_code or name</td>
</tr>
<tr>
<td>terrain_code</td>
<td>a single terrain code, perhaps with overlay</td>
<td>TERRAIN*, *TERRAIN</td>
<td>a shortname or (\*|[A-Z][a-z]+)\^([A-Z][a-z\\|/]+\Z)?</td>
</tr>
<tr>
<td>shortname</td>
<td>a terrain code or a short, capitalized variable name</td>
<td></td>
<td>[A-Z][a-z][a-z]?</td>
<tr>
<td>name</td>
<td>a name or identifier</td>
<td>NAME, VAR, IMAGESTEM, ID, FLAG, *_NAME, *_ID, NAMESPACE, BUILDER, *_VAR</td>
<td>anything without spaces that matches no other type</td>
</tr>
<tr>
<td>optional_string</td>
<td>a string value (may be empty)</td>
<td>ID_STRING, NAME_STRING, DESCRIPTION, IPF</td>
<td>a string, or the empty string</td>
</tr>
<tr>
<td>string</td>
<td>a nonempty string not matching any of the preceding types</td>
<td>STRING, TYPE, TEXT, *_STRING, *_TYPE, *_TEXT</td>
<td>a shortname, a name, a stringliteral, or anything that contains spaces and matches no other type</td>
</tr>
<tr>
<td>stringliteral</td>
<td>a string in doublequotes or a translated string</td>
<td></td>
<td>".*" or _.* but not _[a-z].*</td>
</tr>
<tr>
<td>image</td>
<td>an image path, perhaps with [[ImagePathFunctionWML|image path functions]]</td>
<td>*IMAGE, PROFILE</td>
<td>[A-Za-z0-9{}.][A-Za-z0-9_/+{}.-]*\.(png|jpg)(?=(~.*)?)</td>
</tr>
<tr>
<td>sound</td>
<td>a music or sound filename</td>
<td>MUSIC, SOUND</td>
<td>string ending with ".wav" or ".ogg"</td>
</tr>
<tr>
<td>filter</td>
<td>[[FilterWML|WML filter]]</td>
<td>FILTER</td>
<td>any non-quoted string containing "="</td>
</tr>
<tr>
<td>WML</td>
<td>arbitrary WML fragment</td>
<td>WML, *_WML</td>
<td>any non-quoted string containing "=", or the empty string</td>
</tr>
<tr>
<td>affix</td>
<td>a prefix, suffix, or infix for a variable name</td>
<td>AFFIX, *AFFIX, POSTFIX, ROTATION</td>
<td>a shortname or name, or the empty string</td>
</tr>
<tr>
<td>any</td>
<td>anything</td>
<td>*VALUE, [ARS][0-9]</td>
<td>anything</td>
</tr>
</table>

If the actual argument is a macro call {.*}, then it matches any formal. Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in data/tools/Makefile of the source distribution. Here are some of those reports:

; make unresolved: Report on unresolved macro calls and resource references; also report macro argument-type mismatches. (This is what you are most likely to want to do).

; make all: Report all macro and resource file references, not just unresolved ones.

; make collisions: Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand
[http://docs.python.org/lib/re-syntax.html Python regular expressions].

; -h, --help: Emit a help message and quit
; -c, --crossreference: Report resolved macro references (implies <tt>-w 1</tt>)
; -C, --collisions: Report duplicate resource files
; -d, --deflist: Make definition list. (This one is for campaign server maintainers.)
; -e regexp, --exclude regexp: Ignore files matching the specified regular expression.
; -f dir, --from dir: Report only on macros defined under dir
; -l, --listfiles: List files that will be processed
; -r ddd, --refcount=ddd: Report only on macros with references in exactly ddd files.
; -t TYPELIST, --typelist TYPELIST: List actual & formal argtypes for calls in fname
; -u, --unresolved: Report unresolved macro references
; -w, --warnlevel: Set to 1 to warn of duplicate macro definitions
; -p, --progress: Show progress
; --force-used reg: Ignore reference count 0 on names matching regexp
; --extracthelp: Extract help from macro definition comments.
; --unchecked: Report all macros with untyped formals.
; --version: show program's version number and exit

These options are used with a list of directories as arguments; if none is given,
<tt>wmlscope</tt> behaves as though the current directory had been specified as a
single argument. Each directory is treated as a separate domain for
macro and resource visibility purposes.

<tt>wmlscope</tt> recognizes two kinds of namespace, exporting and non-exporting.
Exporting namespaces make all their resources and macro names
globally visible. You can make a namespace exporting by embedding
a comment like this in it:

# wmlscope: export=yes

Wesnoth core data is an exporting namespace. Campaigns are non-exporting;
they should contain the declaration

# wmlscope: export=no

somewhere. <tt>wmlscope</tt> will complain when it sees a namespace with no export
property, then treat it as non-exporting.

You can tell <tt>wmlscope</tt> to ignore stretches of config files
with the following magic comments:

# wmlscope: start ignoring
# wmlscope: stop ignoring

Similarly, you can tell <tt>wmlscope</tt> to ignore multiple or duplicate macro
definitions in a range of lines with the following magic comments:

# wmlscope: start conditionals
# wmlscope: stop conditionals

The following magic comment:

# wmlscope: prune FOOBAR

will cause <tt>wmlscope</tt> to forget about all but one of the definitions of
<tt>FOOBAR</tt> it has seen. This will be useful mainly for symbols that have
different definitions enabled by an <tt>#ifdef</tt>.

Due to a preprocessor limitation, inline macros cannot contain a documentation
string. If you need to document these macros in the HTML macro reference, you
can use the following directive:

# wmlscope: docstring FOOBAR

The docstring for the FOOBAR macro will be collected until a non-comment line,
a <tt>#define</tt> or another <tt># wmlscope: docstring</tt> are found. External
docstrings '''''must''''' be defined before the macro to which they refer; defining
two or more external docstrings keeps only the most recent one, but having both an
external and an internal docstring is allowed (in this case, the internal one
will be appended to the external one in the macro reference).

This tool does catch one kind of implicit reference: if an attack name
is specified but no icon is given, the attack icon will default to
a name generated from the attack name. This behavior can be suppressed
by adding a magic comment containing the string "no-icon" to the <tt>name=</tt>
line.

The checking done by this tool has a couple of flaws:

(1) It doesn't actually evaluate file inclusions. Instead, any
macro definition satisfies any macro call made under the same
directory. Exception: when an <tt>#undef</tt> is detected, the macro is
tagged local and not visible outside the span of lines where it was
defined.

(2) It doesn't read <tt>[binary_path]</tt> tags, as this would require
implementing a WML parser. Instead, it assumes that a resource-file
reference can be satisfied by any matching image file from anywhere
in the same directory it came from. The resources under the '''''first'''''
directory argument (only) are visible everywhere.

(3) A reference with embedded {}s in a macro will have the macro's
formal args substituted in at WML evaluation time. Instead, this
tool treats each {} as a .* wildcard and considers the reference to
match '''''every''''' resource filename that matches that pattern.
Under appropriate circumstances this might report a resource filename
statically matching the pattern as having been referenced even
though none of the actual macro calls would actually generate it.

Problems (1) and (2) imply that this tool might conceivably report
that a reference has been satisfied when under actual
WML-interpreter rules it has not.

The reporting format is compatible with GNU Emacs compile mode.

For debugging purposes, an in-line comment of the form

# wmlscope: warnlevel NNN

sets the warning level.

== wmllint ==

<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:

* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.

* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. If you port such old code, use <tt>wmllint-1.4</tt>, which is located in the same directory as <tt>wmllint</tt>. It will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

<tt>wmllint</tt> also performs various sanity-checking operations, reporting:

* unbalanced tags
* strings that need a translation mark and do not have them
* strings that have a translation mark and should not
* translatable strings containing macro references
* filter references by description= (id= in 1.5) not matched by an actual unit
* abilities or traits without matching special notes, or vice-versa
* consistency between recruit= and recruitment_pattern= instances
* double space after punctuation in translatable strings.
* unknown races or movement types in units

<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

; -h, --help: Emit a help message and quit.
; -c, --clean: Clean up -bak files.
; -D, --diffs: Display diffs between converted and unconverted files.
; -d, --dryrun: List changes (-v) but don't perform them.
; -r, --revert: Revert the conversion from the -bak files.
; -m, --missing: Warn about tags without side= keys now applying to all sides.
; -s, --stripcr: Convert DOS-style CR/LF to Unix-style LF.
; -v, --verbose: Set verbosity; more details below.
; -K, --known: Suppress check for unknown unit types, recruits, races, scenarios, etc.
; -S, --nospellcheck: Suppress spellchecking
; --version: show program's version number and exit
; --config: allows specifying directories to include ('''include_dirs'''), directories to exclude ('''ignore_directories'''), and files to exclude ('''ignore_files''').

The verbosity option works like this:

; -v: lists changes.
; -v -v: warns of maps already converted.
; -v -v -v: names each file before it's processed.
; -v -v -v -v: shows verbose parse details (developers only).

The recommended procedure is this:

# Run it with --dryrun first to see what it will do.
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
# Eyeball the changes with the --diff option.
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
# Test the conversion.
# Use either --clean to remove the -bak files or --revert to undo the conversion.

Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings. It will work automatically with any of [https://github.com/AbiWord/enchant enchant]'s spellchecking backends (including aspell, myspell, ispell, applespell, hunspell, nuspell, and so on, depending on the version of enchant), provided you have the <tt>enchant.py</tt> Python library installed. Note that the spellchecking results can vary depending on which backend enchant decides to use.

wmllint supports a number of magic comments to customize its behaviour and avoid false positives. All magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. In the below explanations, a string of the form <code>[a|b]</code> means you may use either <code>a</code> or <code>b</code> at that location, while a string of the form <code><arg></code> indicates free text substitution.

* <code>ignore</code>: Disables checking of terrains and translation marks on the current line only.
* <code>noconvert</code>: Disables conversion of terrains and image/sound filenames on the current line only.
* <code>markcheck [on|off]</code>: Enables or disables translation mark checking from the current (next?) line onward.
* <code>no-icon</code>: If an attack has no description, without this wmllint adds a dummy description to the attack which is just the name of the attack. With this, this description insertion is suppressed.
* <code>recognize <name></code>: Indicates that the character with the given name exists even though a declaration (ie a <code>[unit]</code> or <code>[side]</code> tag) is not visible.
* <code>whofield <macro> <number></code>: Indicates that the specified macro declares a character whose name is given by the specified argument to the macro.
* <code>whofield clear <macro></code>: Removes the <code>whofield</code> definition for the specified macro.
* <code>who <macro> is <name> <name> ...</code>: Indicates that the specified macro declares one or more characters whose names are given as a space-separated list. This can also be used for macros that auto-recall a list of characters, some of which join later or may die at some point. If a definition for the macro already exists, then the specified names are appended to it. If a name is preceded by a double minus (<code>-- <name></code>) then it is removed from the definition.
* <code>unwho all|<name></code>: Removes the <code>who</code> definition for the specified macro, or all <code>who</code> definitions.
* <code>usage of "<unit>" is <class></code>: Declares the usage of the specified unit (the <code>usage=</code> key in the <code>[unit_type]</code> tag). Useful if you are using macros to generate several similar unit types.
* <code>usagetype <class></code>: Declares a valid usage type for units. <code>usagetypes</code> is also recognized, and a comma-separated list of usage types can be specified.
* <code>validate-[on|off]</code>: Enables or disables stack-based validation checks. Use when you have unbalanced tags in macros.
* <code>unbalanced-[on|off]</code>: Similar to above, the precise difference is unclear.
* <code>no translatables</code>: Suppresses warnings about a missing textdomain declaration in the current file. Make sure the file really does have no translatable strings!
* <code>display [on|off]</code>: Enable or disable warnings about newlines in messages.
* <code>notecheck [on|off]</code>: Enable or disable note consistency checks for unit descriptions.
* <code>deathcheck [on|off]</code>: Enable or disable the check for units speaking in their death events.
* <code>[general|directory|local] spellings <word> <word> ...</code>: Declares the specified space-separated list of words to be valid spellings in the specified context. The context <code>local</code> indicates the current file only, while <code>directory</code> means the current file and any siblings in the same directory or subdirectories. The <code>global</code> context indicates the spellings are valid anywhere.
* <code>no spellcheck</code>: Disables spell checking on the current line.
* <code>skip-side</code>: Indicates that there is a missing side declaration at this location that will be provided by a macro expansion.
* <code>match <string> with <notes_macro></code>: Indicates that uses of the specified string in a unit definition (usually a macro, including the curly braces) should be matched up with the specified special notes macro (which is also specified as the full macro with curly braces).
* <code>no ellipsecheck</code>: Disables checking of unit ellipses on the current line.

=== Explanations of <tt>wmllint</tt> diagnostics ===
Some <tt>wmllint</tt> diagnostics may require further explanation for UMC authors to understand; this section will be for providing such explanations, and descriptions of how to solve and/or silence them.

In these, <code>%s</code> will be replaced by a string. When the recommended solution also includes a <code>%s</code>, it's a suggestion to copy the string from the error message into your code.

* <code>nonstandard word-wrap style within message</code>: This message meant there was an unexpected newline character within a <code>[message]</code> tag. However, this check was removed in the 1.15.10 release. Pre-1.15.10, add-on developers could silence by putting a <code># wmllint: display on</code> comment before the string and a <code># wmllint: display off</code> comment after the string, however, post-1.15.10, this is no longer necessary.
* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>unknown speaker '%s' of [message]</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the speaker is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is SPEAKER</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>unknown '%s' referred to by id</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the unit is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is UNIT</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
* <code>%s has unknown advancements</code> (in cases where you'd think the advancement ''would'' be known): This means the unit has an advancement that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load mainline units for checking advancements. Note that it's also possible that you just made typo, too, so be sure to check your spelling. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>.description may need hand fixup</code>: This one comes from mucking around with the <code>.description</code> field of unit data manually in a hackish fashion. There isn't really much of a way to work around it, besides just the "don't do that" solution.
* <code>tag stack nonempty (%s) at end of file.</code>: This means that you have unbalanced tags somewhere in the file, e.g. an opener without a closer, or vice versa. This can often be seen when defining macros for unit abilities. A way to fix this warning is to wrap the section with unbalanced tags with a <code># wmllint: unbalanced-on</code> magic comment beforehand and a <code># wmllint: unbalanced-off</code> magic comment afterwards. As having unbalanced tags will also cause issues for other WML maintenance tools, such as <tt>wmlindent</tt> and <tt>wmlxgettext</tt>, you may also want to add separate magic comments for each of them (see their documentation for the form they take).
* <code>unit declaration without side attribute</code>: the default side for a unit declaration when left implicit is side 1. Specify your unit sides explicitly to solve this.
* <code>no %s units recruitable at difficulty %s</code> (even when there are such units recruitable): This diagnostic has to do with matching the <code>usage</code> key of units recruitable by an AI side with their <code>recruitment_pattern</code>. It means the unit has a usage that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can know which mainline units are recruitable. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown movement type</code> (even when you'd think that that movement type ''would'' actually be known): This means the unit has a movetype that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline movement types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>%s has unknown race</code> (even when you'd think that that race ''would'' actually be known): This means the unit has a race that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline races. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>derivation of %s from %s does not resolve</code> (even when you'd think it would): This means that a unit using the [[UnitTypeWML#Other_tags|[base_unit]]] tag specifies a unit ID in that tag that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the core units for its derivation checks. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
* <code>[advancefrom] needs to be manually updated to [modify_unit_type] and moved into the _main.cfg file</code>: This one is pretty self-explanatory: [[UnitTypeWML#Unit_Type|[advancefrom]]] was deprecated in [https://github.com/wesnoth/wesnoth/commit/3950f40f3f0483032bc70b3e57166bd355acd9fc commit 3950f40] due to [https://github.com/wesnoth/wesnoth/issues/3955 issue #3955], and in fact doesn't even work anymore (in 1.16) as per [https://github.com/wesnoth/wesnoth/issues/6204 issue #6204]. The main reason <tt>wmllint</tt> can't fix this automatically is because it could end up being too complicated for it to figure out which files to edit if there are multiple uses of <code>[advancefrom]</code>, and it also doesn't want to assume where to put the [[ModificationWML|[modify_unit_type]]] tag in <tt>_main.cfg</tt>.

== wmlindent ==

Call with no arguments to filter WML on standard input to reindented WML on
standard output. If arguments are specified, they are taken to be files to be
re-indented in place; a directory name causes reindenting on all WML
beneath it.

The indent unit is four spaces. Absence of an option to change this is
deliberate; the purpose of this tool is to ''prevent'' style wars, not encourage
them.

On non-empty lines, this code never modifies anything but leading and
trailing whitespace. Leading whitespace will be regularized to the
current indent; trailing whitespace will be stripped. After processing
all lines will end with a Unix-style <code>\n</code> end-of-line marker.

Runs of entirely blank lines will be reduced to one blank line, except
in two cases where they will be discarded: (a) before WML closing
tags, and (b) after WML opening tags.

It is possible to wrap a section of lines in special comments so that
<tt>wmlindent</tt> will ignore them. You may need to do this for unbalanced
macros (it's better, though, to get rid of those where possible).
Use '<code>wmlindent: {start,stop} ignoring</code>' anywhere in a comment.

It is also possible to declare custom openers an closers, e.g for macros
that are actually control constructs. To do this, use declarations

# wmlindent: opener "{EXCEPTIONAL_OPENER "
# wmlindent: closer "{EXCEPTIONAL_CLOSER "

The lines after an opener will be indented an extra level; a closer
and lines following will be indented one level less. Note that these
declare prefixes; any prefix match to the non-whitespace text of a line
will be recognized.

The public utility macros "<code>{FOREACH</code>" and "<code>{NEXT</code>" come as wired-in exceptions,
because it is not guaranteed that their indent declarations will be processed
before the macro library is reached.

Interrupting <tt>wmlindent</tt> ought to be safe, as each reindenting will be done to a copy
that is atomically renamed when it's done. If the output file is identical
to the input, the output file will simply be deleted, so the timestamp
on the input file won't be touched.

The <tt>--dryrun</tt> option detects and reports files that would be changed
without changing them. The <tt>--verbose</tt> or <tt>-v</tt> option enables reporting
of files that are (or would be, under <tt>--dryrun</tt>) changed. With <tt>-v -v</tt>,
unchanged files are also reported. The <tt>--exclude</tt> option takes a regexp
and excludes files matching it.

If you don't apply this tool to your own WML that you wish to submit, the
mainline-campaign maintainers will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML
that is syntactically unbalanced. Unbalanced double quotes that aren't part
of a multiline literal will also confuse it. You will receive warnings
if there's an indent open at end of file or if a closer occurs with
indent already zero; these two conditions strongly suggest unbalanced WML.

== GUI.pyw ==

Starting from version 1.11.15 and 1.13.0, a GUI (written in Tkinter, plus the themed widgets ttk) is available in the same directory as the other tools. To use it, you need to have a version of Python equal to or greater than 3.1.0 (the 3.0.x series doesn't include the ttk widgets, and as such is unsuitable for this script).

If you're on Linux, be sure to have installed the ''python3-tk'' module, '''or the application won't run at all'''. To install it in a Debian-based distro (like Ubuntu), type this line in a Terminal:
sudo apt install python3-tk

To start it, just double click on the GUI.pyw file. The interface is pretty much self-explanatory, and allows you to run wmllint, wmlscope, wmlindent and wmlxgettext, modify their options, select an add-on and save the tools' output as a text file.

== See Also ==
* [[Translation Maintenance Commands]] (for <tt>wmlxgettext</tt>)

[[Category:Create]]
[[Category:Tools]]

Template:DevDownload

2026-06-28T14:59:08Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.25 | filename=wesnoth-1.19.25-win64.exe |
hash=b29d0e9bed037f4eb7bbeece49dea6a0cce1bc3c4e53e5c3f4a19d53ee7a2271}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.25 | filename=Wesnoth_1.19.25.dmg |
hash=c884e5bb31dfabd8fd56ca5d804174f296d57bffd018da875267e499473cdc6c}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.25 | filename=wesnoth-1.19.25.tar.bz2 |
hash=f0d55de8ee25f3189c6d0ba530c10911939c4cf2d8a6be1d6d7a8f29d31eba4b}}

Template:DevDownload

2026-06-28T14:04:59Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.25 | filename=wesnoth-1.19.25-win64.exe |
hash=b29d0e9bed037f4eb7bbeece49dea6a0cce1bc3c4e53e5c3f4a19d53ee7a2271}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=Wesnoth_1.19.24.dmg |
hash=11d87318b4fc3b83c043bd5e5d675c4ea8ca877904ec77fffecbb9ef050ab5b8}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.25 | filename=wesnoth-1.19.25.tar.bz2 |
hash=f0d55de8ee25f3189c6d0ba530c10911939c4cf2d8a6be1d6d7a8f29d31eba4b}}

Template:DevDownload

2026-06-28T14:04:41Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=wesnoth-1.19.24-win64.exe |
hash=b29d0e9bed037f4eb7bbeece49dea6a0cce1bc3c4e53e5c3f4a19d53ee7a2271}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=Wesnoth_1.19.24.dmg |
hash=11d87318b4fc3b83c043bd5e5d675c4ea8ca877904ec77fffecbb9ef050ab5b8}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=wesnoth-1.19.24.tar.bz2 |
hash=f0d55de8ee25f3189c6d0ba530c10911939c4cf2d8a6be1d6d7a8f29d31eba4b}}

1.19 Roadmap

2026-05-29T05:55:43Z

Pentarctagon:

This page is for consolidating and planning when new features and fixes are intended to land in the 1.19 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here (link is to the 1.17 page, might change for 1.19)].

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

This is just an outline currently, with some point releases for the early, middle and late parts of the branch.

== Note on Single-Player Campaign Reworks ==

We have some campaign reworks planned and in-progress.

* In-hiatus: The Rise of Wesnoth
* In-progress but slower development: Legend of Wesmere (still Hybrid), Asheviere's Dogs (AD)
* post-development: SotBE revisions

The other three might be going into 1.21.x so have been mentioned here just to prepare for an unprecedented development allowances (more assistance in coding, accelerated development speed, etc).

If you have inquiries on the reworks, contact SP rework team leaders (forums/discord):
* Dalas (TSG/TDG/HttT)
* Dwarftough/Mechanical (LoW)
* Gweoddeoran (TRoW)
* LK (SotBE)

New Campaigns added in

* The South Guard: Tutorial
* The Deceivers Gambits, Parts I and II
* Dusk of Dawn
* Heir to the Throne (Revised)

Revised Campaigns:

* Liberty
* The Hammer of Thursagan
* Sceptre of Fire
* Under the Burning Suns

== 1.19.0 (05/26/2024) ==
* Move the Dunefolk into Default Era (Pentarctagon) - completed in #8688

== 1.19.1 (06/16/2024) ==
* [https://github.com/wesnoth/wesnoth/pull/6826 #6826] Merge hardware accelerated unit submerge effect, if possible (Pentarctagon)
** Completed in [https://github.com/wesnoth/wesnoth/pull/8687 #8687].

== 1.19.2 (07/21/2024) ==
* Finish adding ability/weapon special unit tests (Pentarctagon)
* Release tentative TSG re-revision add-on, building on Yumi's work (Dalas)
** Depending on reception, additional development may be needed, or the rework may be dropped altogether.
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.3 (08/18/2024) ==
* Investigate replacing mariadbpp with Boost.MySql (Pentarctagon)

== 1.19.4 (09/15/2024) ==
* Release final (hopefully) TDG add-on. Collect feedback and fix bugs (Dalas)
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.5 (10/20/2024) ==
* [https://github.com/wesnoth/wesnoth/pull/6512 #6512] New type of deprecation warning, when a deprecated attribute is used alongside its replacement (octalot)
* [https://github.com/wesnoth/wesnoth/pull/7082 #7082] Get wmllint running against mainline during CI with no errors (Pentarctagon)
* GUI2 port of the Help Browser (LumiousE/babaissarkar, CelticMinstrel)
** Completed in [https://github.com/wesnoth/wesnoth/pull/3653 #3653]

== 1.19.6 (11/17/2024) ==

== 1.19.7 (12/15/2024) ==
* Unified recruit/recall dialog (LumiousE/babaissarkar) (related issues: [https://github.com/wesnoth/wesnoth/issues/1059 1059], [https://github.com/wesnoth/wesnoth/issues/8829 8829], [https://github.com/wesnoth/wesnoth/issues/5237 5237])
** Completed in [https://github.com/wesnoth/wesnoth/pull/9499 #9499]

== 1.19.8 (01/19/2025) ==

* [https://github.com/wesnoth/wesnoth/issues/8585 #8585], [https://github.com/wesnoth/wesnoth/issues/9035 #9035] Solve all issues with [damage_type] (octalot)
* Go through all the added translatable strings, and check that they're used. For example, look for campaign-specific abilities which aren't used in the campaign. This is on the roadmap twice, I'm planning to do it annually. (octalot, but open to volunteers)

== 1.19.9 (02/16/2025) ==
* Release first half of HttT revision and gather feedback, fix bugs, etc (Dalas)
** This is a VERY rough release date. Probably +/- 2 months.

== 1.19.10 (03/16/2025) ==
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)
* Add "pseudo-queues" as a built-in feature for the multiplayer lobby (pentarctagon)

== 1.19.11 (04/20/2025) ==

== 1.19.12 (05/18/2025) ==
* Improve UtBS. (Hejnewar) This includes:
** Removal and replacement of some abilities, mainly hero ones.
** Better accomodation of high level units to the new recall system.
** Difficulty of Nightmare+.
** Changes to some maps and scenarios, mainly in order to make them more fluid.
* Mercenaries SP/MP campaign (still didn't give up) (Hejnewar) This includes:
** New pixelart terrains and backgrounds (particularily tough for someone without pixelart skills).
* Balance (Hejnewar)
* New MP maps and scenarios. (Hejnewar) This includes:
** New short survival.
** Recovery of long lost mapmaking art.
** New PvP and PvPvE maps, including experimental scenarios with events.

== 1.19.13 (06/15/2025) ==
* Establish clear direction on weather graphics (doofus-01)

== 1.19.14 (07/20/2025) ==

== 1.19.15 (08/17/2025) ==
* Play through any remaining mainline campaigns worth playing through (ie: not LoW, TRoW or SotBE) and add at least a minimum baseline of achievements to them (Pentarctagon)
* Replace TDG's current magic system with an improved and more developer-friendly version (amakriLexa04)

== 1.19.16 (09/21/2025) ==

== 1.19.17 (10/19/2025) ==
* Release second half of HttT revision and gather feedback, fix bugs, etc (Dalas)
** This is a VERY rough release date. Probably +/- 3 months.
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.18 (11/16/2025) ==

== 1.19.19 (12/21/2025) ==

== 1.19.20 (01/18/2026) ==
* Go through all the added translatable strings, and check that they're used. For example, look for campaign-specific abilities which aren't used in the campaign. (octalot, but open to volunteers)
* Take a serious look at supporting a competitive mode/ELO ranking natively (pentarctagon)

== 1.19.21 (02/15/2026) ==
'''This marks the beginning of the string freeze for 1.19'''

== 1.19.22 (03/15/2026) ==

== 1.19.23 (04/19/2026) ==

== 1.19.24 (05/17/2026) ==

== 1.19.25 (06/21/2026) ==

== 1.19.26 (07/19/2026) (Beta 1) ==
'''This marks the beginning of the feature freeze for 1.19;''' the only API changes made past this point must be to fix bugs.

== 1.19.27 (08/16/2026) (Beta 2) ==

== 1.19.28 (09/20/2026) (Beta 3) ==

== 1.19.29 (10/18/2026) (RC1) ==

* Add new screenshots for 1.20

== 1.20.0 (11/15/2026) ==

[[Category:Roadmaps]]

1.19 Roadmap

2026-05-29T05:04:03Z

Pentarctagon:

This page is for consolidating and planning when new features and fixes are intended to land in the 1.19 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here (link is to the 1.17 page, might change for 1.19)].

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

This is just an outline currently, with some point releases for the early, middle and late parts of the branch.

== Note on Single-Player Campaign Reworks ==

We have some campaign reworks planned and in-progress.

* In-hiatus: The Rise of Wesnoth
* In-progress but slower development: Legend of Wesmere (still Hybrid), Asheviere's Dogs (AD)
* post-development: SotBE revisions

The other three might be going into 1.21.x so have been mentioned here just to prepare for an unprecedented development allowances (more assistance in coding, accelerated development speed, etc).

If you have inquiries on the reworks, contact SP rework team leaders (forums/discord):
* Dalas (TSG/TDG/HttT)
* Dwarftough/Mechanical (LoW)
* Gweoddeoran (TRoW)
* LK (SotBE)

New Campaigns added in

* The South Guard: Tutorial
* The Deceivers Gambits, Parts I and II
* Dusk of Dawn
* Heir to the Throne (Revised)

Revised Campaigns:

* Liberty
* The Hammer of Thursagan
* Sceptre of Fire
* Under the Burning Suns

== 1.19.0 (05/26/2024) ==
* Move the Dunefolk into Default Era (Pentarctagon) - completed in #8688

== 1.19.1 (06/16/2024) ==
* [https://github.com/wesnoth/wesnoth/pull/6826 #6826] Merge hardware accelerated unit submerge effect, if possible (Pentarctagon)
** Completed in [https://github.com/wesnoth/wesnoth/pull/8687 #8687].

== 1.19.2 (07/21/2024) ==
* Finish adding ability/weapon special unit tests (Pentarctagon)
* Release tentative TSG re-revision add-on, building on Yumi's work (Dalas)
** Depending on reception, additional development may be needed, or the rework may be dropped altogether.
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.3 (08/18/2024) ==
* Investigate replacing mariadbpp with Boost.MySql (Pentarctagon)

== 1.19.4 (09/15/2024) ==
* Release final (hopefully) TDG add-on. Collect feedback and fix bugs (Dalas)
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.5 (10/20/2024) ==
* [https://github.com/wesnoth/wesnoth/pull/6512 #6512] New type of deprecation warning, when a deprecated attribute is used alongside its replacement (octalot)
* [https://github.com/wesnoth/wesnoth/pull/7082 #7082] Get wmllint running against mainline during CI with no errors (Pentarctagon)
* GUI2 port of the Help Browser (LumiousE/babaissarkar, CelticMinstrel)
** Completed in [https://github.com/wesnoth/wesnoth/pull/3653 #3653]

== 1.19.6 (11/17/2024) ==

== 1.19.7 (12/15/2024) ==
* Unified recruit/recall dialog (LumiousE/babaissarkar) (related issues: [https://github.com/wesnoth/wesnoth/issues/1059 1059], [https://github.com/wesnoth/wesnoth/issues/8829 8829], [https://github.com/wesnoth/wesnoth/issues/5237 5237])
** Completed in [https://github.com/wesnoth/wesnoth/pull/9499 #9499]

== 1.19.8 (01/19/2025) ==

* [https://github.com/wesnoth/wesnoth/issues/8585 #8585], [https://github.com/wesnoth/wesnoth/issues/9035 #9035] Solve all issues with [damage_type] (octalot)
* Go through all the added translatable strings, and check that they're used. For example, look for campaign-specific abilities which aren't used in the campaign. This is on the roadmap twice, I'm planning to do it annually. (octalot, but open to volunteers)

== 1.19.9 (02/16/2025) ==
* Release first half of HttT revision and gather feedback, fix bugs, etc (Dalas)
** This is a VERY rough release date. Probably +/- 2 months.

== 1.19.10 (03/16/2025) ==
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)
* Add "pseudo-queues" as a built-in feature for the multiplayer lobby (pentarctagon)

== 1.19.11 (04/20/2025) ==

== 1.19.12 (05/18/2025) ==
* Improve UtBS. (Hejnewar) This includes:
** Removal and replacement of some abilities, mainly hero ones.
** Better accomodation of high level units to the new recall system.
** Difficulty of Nightmare+.
** Changes to some maps and scenarios, mainly in order to make them more fluid.
* Mercenaries SP/MP campaign (still didn't give up) (Hejnewar) This includes:
** New pixelart terrains and backgrounds (particularily tough for someone without pixelart skills).
* Balance (Hejnewar)
* New MP maps and scenarios. (Hejnewar) This includes:
** New short survival.
** Recovery of long lost mapmaking art.
** New PvP and PvPvE maps, including experimental scenarios with events.

== 1.19.13 (06/15/2025) ==
* Establish clear direction on weather graphics (doofus-01)

== 1.19.14 (07/20/2025) ==

== 1.19.15 (08/17/2025) ==
* Play through any remaining mainline campaigns worth playing through (ie: not LoW, TRoW or SotBE) and add at least a minimum baseline of achievements to them (Pentarctagon)
* Replace TDG's current magic system with an improved and more developer-friendly version (amakriLexa04)

== 1.19.16 (09/21/2025) ==

== 1.19.17 (10/19/2025) ==
* Release second half of HttT revision and gather feedback, fix bugs, etc (Dalas)
** This is a VERY rough release date. Probably +/- 3 months.
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.18 (11/16/2025) ==

== 1.19.19 (12/21/2025) ==

== 1.19.20 (01/18/2026) ==
* Go through all the added translatable strings, and check that they're used. For example, look for campaign-specific abilities which aren't used in the campaign. (octalot, but open to volunteers)
* Take a serious look at supporting a competitive mode/ELO ranking natively (pentarctagon)

== 1.19.21 (02/15/2026) ==
'''This marks the beginning of the string freeze for 1.19'''

== 1.19.22 (03/15/2026) ==

== 1.19.23 (04/19/2026) ==

== 1.19.24 (05/17/2026) ==

== 1.19.25 (06/21/2026) ==

== 1.19.26 (07/19/2026) (Beta 1) ==

== 1.19.27 (08/16/2026) (Beta 2) ==

== 1.19.28 (09/20/2026) (Beta 3) ==

== 1.19.29 (10/18/2026) (RC1) ==

* Add new screenshots for 1.20

== 1.20.0 (11/15/2026) ==

[[Category:Roadmaps]]

Template:DevDownload

2026-05-24T14:40:32Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=wesnoth-1.19.24-win64.exe |
hash=8ec391e8e8e285567fec2535737bd3e5f6e4222f7769734c67ae821e12a2f63b}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=Wesnoth_1.19.24.dmg |
hash=11d87318b4fc3b83c043bd5e5d675c4ea8ca877904ec77fffecbb9ef050ab5b8}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.24 | filename=wesnoth-1.19.24.tar.bz2 |
hash=53044f21e5060ba0eef255ee988773cd109e178159ae2b84fbffdb0201ff25e8}}

CompatibilityStandards

2026-05-18T14:17:38Z

Pentarctagon:

This policy is now outdated. Find the updated policy at https://wiki.wesnoth.org/CompatibilityStandardsV2

Created: 2017-07-11
Updated: 2017-07-11

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

=== How to deprecate ===
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output as well as displayed in-game if running in debug mode. In-game deprecation messages should ONLY appear if debug mode is active. Deprecation notices should, ideally, point the user in the direction of the replacement API that they should be using instead. Documentation on deprecated features should be updated to reflect the deprecated nature of the given API, and should likewise have appropriate signposting toward the preferred replacement.

Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible at least 90% of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore allows for four different levels of deprecation, depending on the severity of the change being made and the cost of maintaining backwards compatibility:

#Deprecated indefinitely — This deprecation level is for changes which are mostly stylistic or organizational in nature and, though the current conventions for core content say not to use them, can theoretically be maintained as wrappers forever. (For example, functions or attributes which have had their names changed or macros which have been replaced with tags.) It is the lowest level of deprecation and is used to signify that a certain API has been replaced with something cleaner which is what should ideally be used, but that there is also no forseeable reason why it will ever need to be forcibly removed while still in use. (This excludes the possibility that an even newer paradigm replaces the one obsoleting this one and causes the need for more aggressive deprecation, in which case the deprecation level should obviously be raised accordingly to match.)
#Deprecated preemptively — This deprecation level is the one which should be aimed for the vast majority of the time. Obsolete APIs which can be implemented in terms of a simple minimal-maintenance wrapper should be deprecated, but left in the code indefinitely. At such time as an obsolete API presents itself as an active obstacle toward further development, it can be slated for removal in the next release, or even removed at will immediately, so long as it has already survived a minimum deprecation period of at least one stable release version. The functions for generating deprecation messages for this level should take a parameter for the first version in which the given feature was deprecated, and their output should reflect whether that period has passed or not, with gentler warnings for those which have not ("this feature is a candidate for removal and may be removed as early as the next version") and harsher warnings for those which have ("this feature is obsolete and may be removed without warning at any time"). Logistically, this differs from "Deprecated indefinitely" only in that it provides a hint to content creators about how likely it is that a future removal will occur, allowing them to prioritize their updates accordingly.
#Deprecated for removal — This deprecation level should be used for features which cannot be maintained as simple wrappers, but which could be maintained as separate, coexisting code. In order to prevent the problem of double-maintenance and code bloat, this level has a built-in lifespan cap of one stable release version following its initial deprecation, after which it will be removed. There may also be cases where a level 1 deprecated feature presents itself as a hindrance to future development, but can be temporarily maintained in this manner as well. In such cases, it is ideal to move the deprecated feature from level 1 to level 2 rather than removing it outright. Deprecation messages for this level should reflect the severity of the deprecation ("this feature will be removed in the next version and requires immediate maintenance").
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed.

It should also be noted that for the purposes of reducing clutter, a deprecated API may also be removed at whatever point that API is no longer being used by any actively maintained add-ons, even if keeping them around would not actively hinder current progress. For the purposes of this rule an "actively maintained add-on" is any add-on in the current stable release or the one directly previous to that. Add-ons which exist for both are to have their current considered the "active" version (meaning that an add-on which used a deprecated API in the previous release but no longer does in the current release is not considered to be actively using that API, and can be disregarded).

=== Post-removal ===
Features which have been removed (subsequent to any of the deprecation levels) should ideally maintain a skeleton of their former interface for at least one stable release version following their removal. This skeleton should print a more detailed error message than the usual "invalid tag/function/object/attribute/whatever" which would result from their complete removal, and the messages should include information on when (and possibly why) the feature was deprecated and where to look for its replacement.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite aproach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== The Net Result - Mutual benefit ===
By deprecating old methods while keeping them around for as long as feasible, the work for content creators to update for a newer release is drastically reduced. They need only update a bare minimum in order to get their content working again, while still being encouraged to update the rest. While it is true that ideally, a content creator would update all deprecated code to use the updated APIs, the human element can't be ignored here. It is extremely frustrating to find that your existing code has thousands of places which need updating before any of it works at all. It is far more pleasant for to be able to do a small amount of tweaking to get something back into working order and then spend time gradually correcting the "uglier" or "less desirable" code while still having something functional to work off of. Counter-intuitive though it may be, indefinite deprecation actually does a better job of encouraging users to update their code than deprecation with a hard removal time does, by avoiding what would otherwise be a massive drain on motivation. Likewise, when things are deprecated as early as possible, developers have the freedom to remove things at will when the need arises, which will better maintain their motivation as well.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

PblWML

2026-05-02T15:44:44Z

Pentarctagon: /* primary_authors */

{{WML Tags}}

To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.

See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.

Note: Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable. {{DevFeature1.15|4}} The translations in the .pbl-files are used, but they are used as a plain text instead of Gettext strings, so don't mark these strings as translatable.

== What goes into a .pbl file? ==

'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''

The following keys are recognized for .pbl files:

=== icon ===
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.

: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctions]] to recolor it. For example:

::icon="units/elves-wood/archer+female-sword-1.png~RC(magenta>brightorange)"
:or
::icon="units/human-peasants/peasant-ranged.png~RC(magenta>white)~CS(24,24,24)"
:or
::icon="units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)"

: Because the add-on manager's UI is dark, recoloring to light colors looks usually better. [https://irydacea.me/projects/wespal Wespal] is a tool that provides a convenient way to preview recolored unit sprites without needing to launch the game with specific WML or Lua edits.

: {{DevFeature1.13|12}} Instead of a standard Wesnoth image, a [[DataURI]] can also be used. This way, an image can be directly included into the _server.pbl file. Take care to leave no trailing newline.

=== title ===
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.
: '''This value is required'''.

=== version ===
: Displayed to the right of the title; it is merely text. However, starting with Wesnoth 1.6, the required format is '''x.y.z''' where '''x''', '''y''' and '''z''' are numbers — and a value for '''x''' greater than ''0'' implies the add-on is complete, feature-wise. Trailing non-numeric elements are allowed, but nothing should appear before or between these numbers. The string of numbers will be modified on the server by inserting or appending zeros as neccesary to meet the required format. All this is necessary for the “Update All” button to work correctly. ([[#Version Key Examples|See Examples]])
: '''This value is required'''.

=== author ===
: Displayed to the right of the version; it is merely text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.

: {{DevFeature1.17|3}} When using forum_auth, this value is a single forum account name which will have the ability to upload new versions of the add-on, delete the add-on from the add-ons server, and update the secondary_authors field.

: {{DevFeature1.19|7}} This value is now used the same as it was pre-forum_auth. It is only used to display in the addons manager.

: '''This value is required'''.

=== passphrase ===
: Not displayed. It prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''

: {{DevFeature1.15|12}}

: It is no longer required to keep the passphrase in the .pbl file at all. If it is not present, then Wesnoth will prompt for it to be entered when uploading or deleting an add-on.

=== description ===
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.
: '''This value is required'''.

=== dependencies ===
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])

=== tags ===
{{DevFeature1.13|12}}
: An optional string including a comma-separated list of keywords used for matching add-ons when typing terms into the Filter box on the top left of the Add-ons Manager. There are no specific requirements on the syntax of the keywords listed here, but a general recommendation is to keep them relevant for players. For example, one might include the add-on's acronym in the tags, the names or acronyms of add-ons to which it is related, and so on.

{{DevFeature1.15|13}} The in-game add-ons manager will show all the tags in the UI, and also includes a drop-down list of tags to filter by. Not all tags are listed in the filter box, and the exact list of tags supported may change before 1.16 is released, but the list is currently:

* '''cooperative''': All human players are on the same team, versus the AI
* '''cosmetic''': These make the game look different, without changing gameplay
* '''difficulty''': Can make campaigns easier or harder
* '''rng''': Modify the randomness in the combat mechanics, or remove it entirely
* '''survival''': Fight against waves of enemies
* '''terraforming''': Players can change the terrain

For example, if an A New Land style add-on had tags ''building'', ''terraforming'', ''anl'', ''city'', and ''survival'' then it would be shown if either ''Terraforming'' or ''Survival'' was selected in the drop-down; the other tags wouldn't affect the filtering.

=== core ===
{{DevFeature1.13|0}}
: An optional string defining the id of the core which the addon is designed for. Defaults to "''default''". Don't specify for an addon which is of type "''core''" itself. Note: DO NOT SET this unless you know why you need it! Giving it an invalid value can lead to mysterious errors with your campaign failing to load!

=== translate ===
: If set to ''true'', the add-on would have been sent to and updated with [[WesCamp|WesCamp-i18n]], if that project were still active. However, as WesCamp is no longer active, this no longer does anything.

: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.

: Note: WesCamp was abandoned in 2014. Instead, please refer to:
* [[GettextForWesnothDevelopers]]
* [[GettextForTranslators#For_add-ons]]
* forum thread: [https://r.wesnoth.org/t46366 Guide: Translating your UMC without WesCamp].

=== type ===
: Indicates the type of the add-on; used to filter listings in the downloads manager dialog. Acceptable values are:

:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}
:* ''campaign'': single player campaign.
:* ''scenario'': single player scenario.
:* ''campaign_sp_mp'': hybrid campaign.
:* ''era'': multiplayer era.
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.
:* ''map_pack'': multiplayer map-pack.
:* ''campaign_mp'': multiplayer campaign.
:* ''scenario_mp'': multiplayer scenario. (See the note below.)
:* ''mod_mp'': multiplayer modification ({{DevFeature1.13|11}} can also used for single-player modifications, although it's still called ''mod_mp'').
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc. Note: Shows as Resources, not Media, in the add-ons interface
:* ''other'': The type to use when no other type fits.
: '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.

: '''This value is required'''.

=== email ===
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.

: '''This value is required if forum_auth is not set to true'''.

=== forum_auth ===
{{DevFeature1.17|3}}
: When set to ''true'', you will be prompted for your forum password when uploading your add-on. The username(s) available to select will be populated from the '''author''' field (before 1.19.7) or the '''primary_authors''' field (1.19.7+). If the username dropdown is empty, make sure to confirm that either the '''author''' or '''primary_authors''' field is present and spelled correctly, depending on what version of Wesnoth you are running.

When set to true, the ''passphrase'' and ''email'' fields are also not required.

=== primary_authors ===
{{DevFeature1.19|7}}
: A comma-delimited list of forum accounts that are allowed to upload new versions of the add-on or delete the add-on from the add-ons server.

: '''Note:''' Due to limitations with Wesnoth's schema validation, this attribute needs to be on the line after '''forum_auth'''.

=== secondary_authors ===
: A comma-delimited list of forum accounts that are allowed to upload new versions of the add-on, but aren't allowed to delete the add-on.

=== [feedback] ===
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.

==== topic_id ====
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, this topic_id corresponds to the series of digits in the ''t=YYYYY'' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!

=== [translation] ===
{{DevFeature1.15|4}}
: Multiple [translation] tags can be used to provide the addon with a localized title and description to be seen in the addons manager. However, it should be noted that the declared translations won't influence the list of supported locales as it depends only on the presence of .mo and .po files for corresponding languages.

==== language ====
: The target language code for the translation. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/] . You can use either its contracted version (like ''sv'' for Swedish) or a more precise variety (like ''zh_CN'' or ''ca_ES@valencia'').
: '''This value is required'''.

==== title ====
: The translation of addon's title for the target language.
: '''This value is required'''.

==== description ====
: The translation of addon's description for the target language.

The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== Examples ==

=== Dependency Key Example ===

The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:

dependencies=Imperial_Era,Era_of_Myths

=== Version Key Examples ===

{{DevFeature1.17|13}} the schema validation rejects many of the '''good''' examples. https://github.com/wesnoth/wesnoth/issues/7396

The following are examples of '''good''' version values:

version="1.5"
version="0.11.4"
version="0.1.4beta"
version="1.5c"

The following are examples of '''bad''' version values:

version="Beta1.5"
version="Incomplete (0.3.4)"

In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.

Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.

0.5 < 1.0
1.5 < 1.5c
1.0 < 1.0.1
1.0c < 1.0.1a
1.0.1a < 1.0.1c
1.0 Final < 1.0.1 Beta

=== Example .pbl File ===

<syntaxhighlight lang=wml>
title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"
[feedback]
topic_id=12345
[/feedback]
# Note: the translation feature works on version 1.14.14, 1.15.4 and later only
[translation]
language="ru"
title="Моя Кампания"
description="Вам придётся завалить немало плохишей. Но пока что готова лишь первая карта."
[/translation]
[translation]
language="zh_CN"
title="我的竞选"
description="你会杀死很多坏人。但是只完成了第一张地图。(translated online)"
[/translation]
</syntaxhighlight>

== See Also ==

* [[IGNFileFormat]]
* [[FancyAddonIcons]]
* [[ReferenceWML]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

Template:DevDownload

2026-04-23T23:50:42Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.23 | filename=wesnoth-1.19.23-win64.exe |
hash=69d2d16d491d1cb374a9a687cd23b803b44775ecb8339641abe45bef4bd273d9}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.23 | filename=Wesnoth_1.19.23.dmg |
hash=44ecfc8257a0bb48baa958b86e300b2f01d46952deddd0e1770e87160f3958e7}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.23 | filename=wesnoth-1.19.23.tar.bz2 |
hash=f5bd748ead5b0b9c838fa95ac6142cceac74354db4e57e1f9de5b9369bd39d48}}

Template:DevDownload

2026-04-23T16:05:26Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=wesnoth-1.19.22-win64.exe |
hash=805a9da0b230f4334431704ba0cea6b8dcb4613da2530fcf1f315ff382ec67e2}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=Wesnoth_1.19.22.dmg |
hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=wesnoth-1.19.22.tar.bz2 |
hash=dccf874092cf42dfbef61e30217f55d40ab4608532ff6dba3be7c052ca3e0c66}}

Template:StableDownload

2026-04-23T16:05:08Z

Pentarctagon:

<noinclude>
== Stable (1.18 branch) ==
</noinclude>
==== Windows (10 1903 and later, 64-bit only) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.7 | filename=wesnoth-1.18.7-win64.exe |
hash=1ebe433b8f7b526944b63d15caf11f42481375130431237b3f1139a517c7c7bb}}

==== macOS (10.12 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.7 | filename=Wesnoth_1.18.7.dmg |
hash=258f797ad4ae1f82b4479706875a372857c17130e221689c56647234513eca5f}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.7 | filename=wesnoth-1.18.7.tar.bz2 |
hash=d6b50cfdf4388954a1c3da66a61abacdc7643a17aa78a16196e16e720a661fc2}}

CompatibilityStandardsV2

2026-04-23T15:57:16Z

Pentarctagon: /* Deprecation levels - When to remove deprecated features */

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed. This level should also be used for macro and method stubs containing only an error message describing what was removed and why, as well as if an API feature is found to have a security vulnerability which can't be fixed.

APIs that are clearly labeled as being experimental, such as a WML tag having "experimental" in the name or a lua function having "experimental" in its name or package, can be be removed or deprecated at any level at any time. These are APIs which UMC authors use at their own risk.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityStandardsV2

2026-04-23T15:54:15Z

Pentarctagon: /* Deprecation levels - When to remove deprecated features */

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed. This level should also be used for macro and method stubs containing only an error message describing what was removed and why, as well as if an API feature is found to have a security vulnerability which can't be fixed.

APIs that are clearly labeled as being experimental, such as a WML tag having "experimental" in the name or a lua function having "experimental" in its name or package, can be be removed at any time. These are APIs which UMC authors use at their own risk.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityStandardsV2

2026-04-23T15:33:54Z

Pentarctagon: /* Deprecation levels - When to remove deprecated features */

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed. This level should also be used for macro and method stubs containing only an error message describing what was removed and why, as well as if an API feature is found to have a security vulnerability which can't be fixed.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityStandardsV2

2026-04-23T15:33:26Z

Pentarctagon: /* When to deprecate */

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed. This level should also be used for macro and method stubs containing only an error message describing what was removed and why.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityStandardsV2

2026-04-20T22:54:45Z

Pentarctagon: /* Deprecation levels - When to remove deprecated features */

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Security ====
If an API is found to have a security flaw that can't be fixed, then it should not be deprecated, it should be immediately removed.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed. This level should also be used for macro and method stubs containing only an error message describing what was removed and why.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityStandardsV2

2026-04-20T22:54:33Z

Pentarctagon: /* Deprecation levels - When to remove deprecated features */

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Security ====
If an API is found to have a security flaw that can't be fixed, then it should not be deprecated, it should be immediately removed.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed.

This level should also be used for macro and method stubs containing only an error message describing what was removed and why.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityStandardsV2

2026-04-19T02:40:35Z

Pentarctagon: Created page with "As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need..."

As a piece of software matures, there are often new designs, paradigms, and idioms developed which are superior to old ones. This creates an inherent conflict between the need for progress and the need for compatibility. Wesnoth is no exception. This document describes Wesnoth's approach toward resolving that conflict in a way which is most beneficial to both goals, as well as the rationale behind this approach.

== Policy ==
This policy defines how the creation of new Wesnoth APIs and the deprecation and removal of old ones are to be handled. For the purposes of this document "API" means "any technical channel by which a content creator interacts with the game engine". This includes, but is not limited to: preprocessor macros, WML tags, WFL functions, IPFs, and the Lua API. Note that this policy applies only to software APIs. Core content such as sprites, portraits, animations, lore, etc. are to be updated freely, without consideration for stylistic or literary conflicts that such content changes may present to add-ons.

=== When to deprecate ===
==== Adding a better API ====
Any time a superior API is introduced which has '''complete feature-parity''' with an existing API, the old one should be immediately deprecated. Note that in most cases, in order to be considered to have "complete feature-parity", the API should be available in the same language or area of the code as the obsolete one was. For example, the introduction of a more powerful API in Lua which can accomplish a superset of the functionality which had previously been available with a certain WML tag would not obsolete that WML tag. Exceptions can be made to this rule in cases where it is clear that the feature does not make a lot of sense in its current language or area, and was merely there for legacy reasons (such as the proper place for it not having been introduced yet at the time of its creation). Such exceptions should be determined by developer consensus.

==== Preventing needed fixes or improvements ====
In such cases where a feature is preventing an important new feature from being added or makes it impossible to fix a problem impacting players, it can be preferable to deprecate the API to allow for the necessary changes to be made. APIs deprecated for this reason should still follow the deprecation schedule as normal, unless the fix or improvement is urgently needed.

==== Actively harmful ====
If an API is found to cause significant problems for players or UMC authors, such as being prone to causing crashes while also very difficult to properly fix, corrupting saves and replays when not used correctly while being difficult to use correctly, or other similar situations, then such APIs should be deprecated and removed regardless of whether there is a replacement available.

==== Security ====
If an API is found to have a security flaw that can't be fixed, then it should not be deprecated, it should be immediately removed.

==== Unused ====
Any API that is not used in mainline and also is not used by the most recent version of an add-on on the add-ons server of the current or previous stable release can be deprecated. For example, if an add-on for 1.16 uses a deprecated API but the updated version of the add-on for 1.18 does not, then that add-on is not considered as currently using the API. Once deprecated for this reason, a new add-on being uploaded that uses the API is not a reason to undeprecate it.

This does not need to be a passive process where developers simply check the add-ons server for whether an API is used - developers who want to deprecate an API for removal can proactively talk to and work with UMC authors to help update their add-ons to remove usage of said API. This can be anything from talking with them online about how to update to submitting updated code directly (ie: opening a PR against an add-on's public git repository).

Deprecating and then removing APIs that are unused is the most preferred approach since their removal does not have any impact on UMC authors.

=== When NOT to deprecate ===
==== Style ====
Deprecation should not be done purely for reasons of style. This is very subjective and prone to change as new contributors join and current contributors leave or become less active. As such, allowing deprecation for stylistic reasons would lead to entirely unnecessary work for UMC authors as developer preferences change over time.

==== Renaming ====
While there can be exceptions, it is rarely a net positive to deprecate an API simply for the sake of renaming it to something else. It is preferable to either add a second name for the same function, leaving the old name as-is, or simply live with the current name rather than expecting all UMC authors using the API to update to the new name.

==== Any other reason ====
Accepted reasons for deprecating APIs should be something that's discussed and agreed upon by the development team while also, ideally, including UMC authors. It should not become the norm that additional reasons to deprecate APIs are treated as exceptions and left as an increasingly forgotten discussion on Discord, IRC, or the forums - they should be added to here with the reasoning behind them.

=== Deprecation awareness ===
==== Conflicting goals ====
When deprecating APIs there is an inherent conflict in terms of how to make UMC authors aware of the deprecation. After all, if they aren't aware something is deprecated, they can't know they may need to update their add-on. Therefore, deprecations need to be displayed in a place where they will see them and most UMC authors don't look at Wesnoth's logs unless there's some other issue they're investigating. At the same time, deprecation warnings aren't relevant to players and spamming deprecation warnings is not an effective way of communicating what the issues are.

==== A middle ground ====
Each deprecated feature should make use of an appropriate deprecation function call for that language or subsystem to ensure that the appropriate deprecation notice is printed to the log output. Additionally, deprecation warnings should be displayed in-game in the following cases:
* If the player is running a development version, level 3 and level 4 deprecations should be shown in-game by default.
* If the player enables debug mode then all deprecation warnings should be shown, regardless of whether they're using a stable release or a development release.

==== Documentation ====
It is also not enough to only display a warning at runtime when something deprecated is encountered. It is the responsibility of the development team to proactively make UMC authors aware of the deprecations and removals being done. To accomplish this:
* When an API is deprecated, and again if it's later removed, its deprecation or removal must be documented in the appropriate section of the changelog for the version it was deprecated or removed in.
* Likewise, it should be added to https://wiki.wesnoth.org/CompatibilityBreakingChanges

Additionally, it is not enough to simply say that an API is deprecated. In the deprecation message itself as well as in the changelog and https://wiki.wesnoth.org/CompatibilityBreakingChanges, a description must be included as to why it was deprecated or removed and how UMC authors can update their add-ons to address it.

Lastly, it should be understood that "removed" doesn't necessarily mean that the API is entirely gone from Wesnoth's codebase. There is no maintenance burden to keeping macro or method stubs that do nothing aside from printing an error message describing what was removed and why. Keeping such stubs around is highly encouraged as it is helpful for UMC authors trying to update very old add-ons to the current version of Wesnoth.

=== How to deprecate ===
Every effort should be made to create the simplest possible wrappers which will translate from an obsolete API to the updated one. Such wrappers should ideally be organized into their own compatibility file or module, and set up in such a way that the internals of the updated API will not affect how the old calls get wrapped to the new one. Essentially, the idea is to create a set-it-and-forget-it compatibility wrapper which will continue to work regardless of updates made to the newer API.

Additionally, in all cases where it's practical, the wmllint tool must be updated to be able to automatically handle updating add-ons for anything that's been deprecated except for APIs deprecated at level 1. While developers are still heavily encouraged to add wmllint support for level 1 deprecations, it is not required as these do not show deprecation warnings by default and are expected to continue working indefinitely.

=== Deprecation levels - When to remove deprecated features ===
While creating simple compatibility wrappers should be possible most of the time, it would be unreasonable to assume that this approach will be viable in absolutely every case. Wesnoth's compatibility policy therefore has four different levels of deprecation which are used to set expectations for when and if an API is expected to be removed:

#Deprecated indefinitely — This deprecation level is for changes which have newer preferred alternatives but, barring any unforeseen issues, have little to no maintenance impact and should be kept indefinitely in order to reduce the work required for UMC authors to maintain their content. For example, functions or attributes which have had their names changed, macros which have been replaced with tags, macro stubs containing only an error message describing what was removed and why, or simple wrappers with little to no maintenance overhead. If future large scale changes make it impractical to maintain an API deprecated at this level then the deprecation level should be raised accordingly. This is generally the preferred deprecation level - higher deprecation levels are for APIs which are intended for eventual removal and must be weighed against the maintenance work this forces upon UMC authors.
#Deprecated with the intention of future removal — This deprecation level is for APIs which will be removed in a future version, but the version they are removed in has not yet have been decided. Barring urgent circumstances, all APIs that are deprecated with the intention of being removed '''must''' start with being deprecated at level 2 for 1-2 development cycles at minimum depending on the impact of the API's removal on UMC authors. Once the API has spent the necessary amount of time at deprecation level 2, it can be moved to deprecation level 3. It is not allowed to deprecate an API at level 2 and change it to level 3 in the same development cycle. There is no maximum amount of time that an API can remain deprecated at level 2.
#Deprecated for removal in a specific version — This deprecation level is for APIs which were previously deprecated at level 2 and now have a future version at which they will be removed. The version an API is removed in must be at least two development cycles after the API was deprecated at level 2. It is not allowed to move an API to deprecation level 3 and then remove it in the same development cycle.
#Removed without deprecation — This level should be used EXTREMELY rarely, and only in cases where it is ABSOLUTELY NECESSARY. Occasionally, an update to a feature will change the underlying architecture in such a fundamental way that the old paradigm cannot coexist with the new one no matter how much redundant code one would create. While this kind of scenario is extremely rare, and every effort should be made to find creative solutions to avoid it, there are occasionally cases where it truly is impossible to maintain both methods even in the short term. This level should only be used with broad developer consensus, after the majority of active developers familiar with the feature in question have given at least some thought to trying to deprecate gracefully and failed.

== Rationale ==
The above policy is the result of a large amount of thought, discussion, and debate. Following is a brief outline of the considerations and goals on both sides of the problem, why there is an inherent conflict between them, some failed approaches to resolving the conflict, and how the final policy ultimately maximizes the pursuit of both goals.

=== The Problem - The paradox of progress ===
Invariably, as development on any project moves forward, developers will realize that there are better, cleaner, or more elegant ways to structure things than they had been previously. These changes can be to improve efficiency, make an API more intuitive, keep code better organized, make common tasks more straightforward, or accomplish any number of other positive things. These changes can also make the development of additional features much more viable. In short, progress is good.

On the other hand, a content-heavy program such as Wesnoth relies on the ability of content creators to efficiently create, maintain, and update their content. Too many changes all at once will force creators of existing content to spend obscene amounts time updating their creations just to keeping them up-to-date and in working order. This can lead to a high amount of frustration, a drop in motivation, and a decline in content being created. In short, progress is bad.

=== Backwards Compatibility - benefits and drawbacks ===
Most of the time, older paradigms can still be maintained in a manner in which they coexist with the newer ones. This allows for existing content to continue functioning, while at the same time allowing and encouraging new content to be created using the newer methods. However, maintaining such code can be problematic in the following ways:
#There may eventually be architectural changes a developer would want to make where the old method's square peg no longer fits, even forcibly, into the new method's round hole.
#Having compatibility code hanging around may, depending on how it is implemented, mean that any updates made to the feature, module, or subsystem in question would have to made in both the new, cleaner design, and the older, poorly structured one, adding more work for developers.

=== The Naive Approach - Deprecate and remove everything old ===
One approach to balancing old and new is to deprecate the old and slate its eventual removal after either a certain amount of time has passed or a certain number of subsequent versions have been released. This sounds good in theory, but in practice, there will be many changes which are minor or cosmetic in nature and which will add up. Things like replacing macros with WML tags, updating the name of an API call or order of parameters to be more consistent with other similar functions, or switching from a functional to an object-oriented structure are very good for organizational purposes, but will result in a large amount of maintenance required on the part of content creators to keep existing code operational, and for very little real gain. This approach invariably leads to the situation where so much is being changed from one version to the next that creators turn into maintainers, forced to spend nearly all of their time trying to stay ahead of the update curve in an attempt to keep their existing content working, and leaving them very little time and motivation to create new content. And of course, by the time they're finished painstakingly updating their existing code for every little change made for the current release, whoops, there's a new release with a whole slew of new changes that need accounting for. It simply becomes unmanageable.

=== The Naive Approach - Deprecate and remove only when necessary ===
The opposite approach would be to keep all existing paradigms until they actively interfere with a new architecture or create a double-maintenance problem. While this approach does cut down on the maintenance burden by ensuring that content using an older design continues to work, it hinders progress by the fact that the moment at which it first becomes clear that an architectural or double-maintenance problem will occur is exactly the same moment at which keeping the old structure around becomes problematic. Beginning a deprecation cycle at that point and then having to "wait out" the old paradigm will cause an unacceptable delay in development.

=== The Middle Ground - Deprecate everything old, remove only when necessary ===
Most of the time, older APIs can be implemented in terms of their newer, cleaner counterparts through the use of things like simple wrappers, parse-translators which re-write the older paradigm's code in terms of the new one, or other relatively low-maintenance "set-it-and-forget-it" approaches. These simple wrappers are not really detrimental to making progress, don't require updating when the new APIs internals are changed, and can usually be organized into their own files and/or modules so that they don't clutter the cleaner code. Many such wrappers will never truly present either of the backwards compatibility drawbacks mentioned above. As such, there is really no detriment to keeping them around indefinitely. However, occasionally, a new idea or approach will be put forth that updates the newer paradigm in such a way that the older one can no longer cleanly wrap to it. This usually happens, as inspiration is wont to do, suddenly, unexpectedly, and without warning. As such developers need the flexibility to be able to remove outdated code as freely as possible when the situation requires. Therefore, the ideal solution would be to deprecate any API which has newer, feature-complete ways to do it, while leaving it in the codebase until such time as its presence becomes a hindrance. Essentially, deprecation need not necessarily mean "this WILL be removed" so much as "this is now a candidate for removal". By separating the concepts of deprecation and removal, both goals can be better served.

=== Undefined removal timeline - issues encountered ===
In practice however, simply stating something is a candidate for removal while providing no further information on when it will actually be removed causes multiple issues:
* When a deprecated API is causing a maintenance burden worthy of removal is a subjective decision, often leading to debates over removal any time a developer decides it's time for an API to be removed, initially deprecated, or moved to a higher deprecation level.
* Lack of developer incentive to provide good documentation and support for the deprecation of the API given there's no particular timeline for when it will actually cause issues for UMC authors.
* UMC authors often don't find out about deprecated APIs and so can't possibly migrate to the new APIs.
* UMC authors aren't provided the documentation or tooling support needed to make updating their add-ons easier.
* UMC authors may simply decide there's no reason to update to the new API even if they know it's deprecated and how to update their add-on. After all, why spend time updating APIs that may stick around forever?
* Giving a version that an API '''may''' be removed instead of a version that it '''will''' be removed is not as clear as it may seem to UMC authors who aren't already aware of how Wesnoth handles deprecation. This can lead to UMC authors ignoring deprecation warnings after seeing such warnings for APIs which provide a version that's years old.

=== Certainty is also a benefit ===
Wesnoth continues to exist today in large part because of the content made by its community. As such, developers should always be sparing in what they choose to deprecate and what they choose to remove, so that UMC authors can update their content to the latest version of Wesnoth without needing to make a herculean effort every couple of years.

But, for cases where APIs are removed, the benefit of providing certainty for when that will happen outweighs the flexibility of being able remove them at any time after they been marked as deprecated. It encourages developers to provide the documentation and tooling support to make it easier for UMC authors to update their add-ons, and it lets UMC authors know when they can expect deprecated APIs to be removed rather than it effectively happening at random when a developer decides a deprecated API needs to be dropped.

=== More Complex Cases - One size does not fit all ===
There may, however, be cases where the obsolete API cannot be implemented cleanly in terms of the updated one and must be maintained separately, or, in extremely rare cases, cannot coexist at all. There needs to be some leeway for such cases as well. In the former case, it therefore makes sense to allow for a feature to be deprecated pending removal after the shortest reasonable deprecation period. In the latter case, there is obviously no choice but to make the change and remove the old immediately. Developers should, naturally, be encouraged to find creative solutions to avoid such cases, but it is inevitable that there will eventually be a few cases where no graceful transition procedure can be found. These more aggressive forms of deprecation should only be done with developer consensus, and only after all options of creating a backwards-compatible transition have been exhausted.

=== Graphics - The exception that proves the rule ===
The one area where backwards compatibility should NOT be a factor is graphical changes. Any change to the terrain graphics, unit sprites, or portrait images has the potential to result in visually-incompatible custom content. Core content creators cannot be expected to maintain a deprecated visual style alongside a more modern one, as any approach toward doing so would add an unreasonable amount of bloat and overhead, and make it very difficult for core graphics to be updated without having to do double the work. In addition, add-ons will continue to function even with such visual incompatibilities present, they just won't look right. As such, it can be said that stylistic incompatibilities fall more within the realm of content than of code, and it is not unreasonable to expect a content creator to... well... create content. Expecting the graphical style to remain backwards-compatible would be just as unreasonable as expecting stories, help descriptions, or other forms of lore to never change because they may introduce plot holes into add-on stories. Essentially, since the goal of the software portion of Wesnoth is, at its heart, merely to facilitate the creation and advancement of this kind of content, core content needs to be free to develop unhindered by considerations for add-on content.

CompatibilityBreakingChanges

2026-04-14T02:07:13Z

Pentarctagon: Pentarctagon moved page User:Bssarkar/CompatibilityBreakingChanges to CompatibilityBreakingChanges

This lists removed WML functionality and helpful hints for avoiding pitfalls.

The previous list is available [https://forums.wesnoth.org/viewtopic.php?t=58532 here].

== Compatibility breaking changes between 1.18 and 1.19/1.20 ==

=== Compatibility breaking (requires updates to work) ===

* '''[kill]''' now reduces target unit hitpoints to 0 before triggering '''last_breath, die''' events. This affects mentioned events that rely on [have_unit] conditions.
* WFL Removed properties '''unit.side''' and '''terrain.owner'''. Use '''unit.side_number''' and '''terrain.owner_side''' instead. They return 1-indexed side, removed properties returned 0-indexed side.
* Abilities with both '''add''' and '''sub''' now calculate value differently
* rotate_loc_around formula now works
* [era] with id=era_dunefolk does not exist anymore
* [side]'s leader attribute has been removed
* [side]'s [variables] tag is now used to set side variables. Use [side]'s [leader] tag to set a unit variable.
* Setting gold to decimal value fails with error. Previously it was converted to int automatically. As of 1.19.21, automatic conversion is only done in [gold], but not in Lua or [modify_side].
* The following macros were removed ([https://github.com/wesnoth/wesnoth/pull/11126 #11126])
** EARLY_FINISH_BONUS_NOTE
** NO_EARLY_FINISH_BONUS_NOTE
** NO_GOLD_CARRYOVER_NOTE
** NEW_GOLD_CARRYOVER_NOTE_100
** NEW_GOLD_CARRYOVER_NOTE_40
** NEW_GOLD_CARRYOVER_NOTE_20
** MISSILE_FRAME_FIREBALL
** MESSAGE
** STORY_PART_SPEECH
** LOYAL_UNDEAD_UNIT
** ON_SIGHTING
** MAKE_AI_SIDE_PERSISTENT
** DRAKE_FLYING_ANIM
** NO_INTERRUPT_NO_UNDO
** ENABLE_NIGHTBLADE

=== Deprecations (will continue to work for now) ===
* rechange [experimental_filter_ability/active] and [experimental_filter_specials] to [filter_ability] and [filter_specials] and make "experimental_" deprecated.

=== New features (help fill this list, https://wiki.wesnoth.org/Special:WhatLinksHere/Template:DevFeature1.19) ===
* StandardAbilityFilter, including [https://github.com/wesnoth/wesnoth/pull/7814 7814]
* [resistance] min_value
* [attack] alignment
* New events '''unit_hits''', '''unit_misses'''
* Positive '''attack_weight''' now affects weapon selection
* Unit attack [effect]+Lua+formula API min_range and max_range
* Lua unit attributes fearless and healthy
* wesnoth.game_config shows some color-related values
* wesnoth.units.rebuild
* stringx.ends_with, stringx.starts_with
* Unit formula new attributes objects, advancements_taken, traits_count, objects_count, advancements_taken_count, fearless, healthy
* Formula functions lerp_index, ends_with, replace_all, starts_with, get_palette
* Custom themes https://wiki.wesnoth.org/GUIToolkit#Custom_themes
* Abilities and specials now support [event] (does not work correctly due to [issue]10819[/issue])
* Ability & Weapon specials registry ([https://github.com/wesnoth/wesnoth/pull/10644 10644]) (does not work correctly if ability contains [event] due to [issue]10819[/issue])
* [effect][remove_specials]
* Expose unit pick dialog to Lua as a simple API call ([https://github.com/wesnoth/wesnoth/pull/8829 8829])
* [fire_event][data] can be accessed from other event as $data
* Unit Type Editor
* [era]auto_sort allows to use custom faction ordering
* [terrain_defaults] formula is now working as expected in case formula evaluates to null
* [set_menu_item] description substitutes variables when rightclick is used
* [defense]
* [resistance_defaults] is not causing OOS in random maps anymore
* Ability/weapon special descriptions support po variables in descriptions like '''$add''', '''$sub''' etc that contain the value of the relevant key. ([https://github.com/wesnoth/wesnoth/pull/10053 10053], [https://github.com/wesnoth/wesnoth/pull/10293 10293], [https://github.com/wesnoth/wesnoth/pull/10749 10749])
* Ability/weapon special help page ids now follow the format: '''ability_<unique_id>''' or '''weaponspecial_<unique_id>''' ([https://github.com/wesnoth/wesnoth/pull/11012 11012]).
* A lot more functions were added to https://wiki.wesnoth.org/LuaAPI/types/widget with https://wiki.wesnoth.org/index.php?title=LuaAPI%2Ftypes%2Fwidget&type=revision&diff=74843&oldid=74842

User:Bssarkar/CompatibilityBreakingChanges

2026-04-14T02:07:13Z

Pentarctagon: Pentarctagon moved page User:Bssarkar/CompatibilityBreakingChanges to CompatibilityBreakingChanges

#REDIRECT [[CompatibilityBreakingChanges]]

PreprocessorRef

2026-04-13T15:42:13Z

Pentarctagon: /* #deprecated */

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However, the '''WML preprocessor''' allows the inclusion of more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [https://www.wesnoth.org/macro-reference.html the macro reference] for the list of predefined core macros.

Macros have scoping rules such that addons have separate preprocessing contexts, meaning that they can be overridden however an author of UMC wishes to override them, without worrying about breaking other add-ons.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. <code>#define-#enddef</code> blocks cannot be nested inside another <code>#define</code>, as of Wesnoth 1.19.

As an example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation|WML Optimisation]].

==== Whitespace in Macros ====

When expanding a macro, '''''all''''' whitespace in the definition of the macro is preserved. The <tt>#arg</tt> declarations for optional arguments are removed including the final newline. The body of the optional argument (the default value) is similarly processed just as if it were a macro, so all whitespace is preserved.

There are two main practical implications of these rules:

* When using a macro to define simple constants to be used inline in the middle of an attribute value, the entire content and the <tt>#enddef</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_CONSTANT
42#enddef</syntaxhighlight>
* If using a macro inside a quoted string, you should not indent the contents of the macro, as the indentation will be preserved upon macro substitution.
* Similarly if you use an optional argument in the middle of an attribute value, the entire content and the <tt>#endarg</tt> must be on one line, like so:
: <syntaxhighlight lang=wml>
#define MY_MACRO
#arg OPTIONAL_ARG
default#endarg
key = "composite {OPTIONAL_ARG} value"
#enddef</syntaxhighlight>

=== #arg ===

{{DevFeature1.13|7}}

'''Syntax: #arg ''symbol'' ''<newline>'' ''default value'' #endarg'''

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

For a multiline optional argument defined and called as follows:
<syntaxhighlight lang="wml">
#define MY_MACRO
#arg MULTILINE
[some_tag]
some_attribute = "some value"
[/some_tag]
#endarg
...
#enddef

{MY_MACRO (MULTILINE=[other_tag]
other_attribute = "other value"
[/other_tag])}
</syntaxhighlight>

'''Note:''' As with #enddef, the final line break before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a line break in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''. Wesnoth expects this to be done when overriding an existing macro, and will warn you if you redefine an existing macro without an explicit #undef before it.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. If they are already quoted, space inside quotes will be preserved even without parentheses. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

This way even complex arguments can be passed:

<syntaxhighlight lang="wml">
{MODIFY_UNIT (
[filter_adjacent]
canrecruit=yes
[/filter_adjacent]
) side 2}
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-defined''. If not, it will be replaced by ''substitution-if-not-defined'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-defined'' [#else ''substitution-if-defined''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as [[#Inclusion_directive_.7B.7D|include directives]].

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

=== #deprecated ===

{{DevFeature1.13|11}}

'''Syntax:''' '''#deprecated 1 [''message'']'''

'''Syntax:''' '''#deprecated 2 ''version'' [''message'']'''

'''Syntax:''' '''#deprecated 3 ''version'' [''message'']'''

'''Syntax:''' '''#deprecated 4 [''message'']'''

The first argument is the deprecation level, while ''version'' is the first Wesnoth version where this deprecated file/macro might to be removed. ''message'' is the optional deprecation message. The recommended usage is to provide ''message''.

The effect of this directive depends on whether it appears within a macro definition.

* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.

Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)

If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

Note that except during an actual game, '''MULTIPLAYER''', '''EDITOR''' and previous campaign defines, are not guaranteed to be undefined, especially when coming back to the titlescreen. So it is not enough to hide contents inside of an #ifdef to prevent them from being seen by the campaign selection dialog, for example for multiplayer specific '''[campaign]'''s or '''[modification]'''s '''type=mp''' must be used.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line). Can also be set by typing <code>:</code> to bring up [[CommandMode]], then typing <code>debug</code>, and then restarting the scenario.
* '''APPLE''': defined while processing the main game data when running on Mac OS X. This primarily exists to switch Control for Command in hotkeys, which is why there are no defines for other platforms.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.
* '''CURRENT_FILE''': Expands to the name of the current WML file.
* '''CURRENT_DIRECTORY''': Expands to the preprocessor path of the parent directory for the current WML file (e.g. for <code><user data dir>/data/add-ons/My_Addon/_main.cfg</code> this evaluates to <code>~add-ons/My_Addon</code>).
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.
* '''SCHEMA_VALIDATION''': defined if the validator is being run.
* '''__WMLUNITS__''': defined when the tool to create [https://units.wesnoth.org units.wesnoth.org] is being run.

A ''very large'' number of additional macros are provided as part of the default game core WML. For a full list of those, check the [https://www.wesnoth.org/macro-reference.html macro reference].

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will first preprocess '''data/core/macros''' and '''data/core/terrain-graphics''', and afterwards the specified path. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulting preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the current directory.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
-p data/gui/macros/_initial.cfg /tmp --preprocess-output-macros=macros
-p myfile.cfg ~/result --preprocess-input-macros=/tmp/macros

When it starts getting complicated, such as a file that depends on multiple other files, it is probably easiest to simply "include" the dependencies:

* File myfile.cfg depends on macros defined in data/gui/macros/_initial.cfg:
Add {gui/macros/_initial.cfg} to the beginning of myfile.cfg
-p myfile.cfg ~/result

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]] (explains relationship between comments and preprocessor directives)
* [[ReferenceWML]]

[[Category: WML Reference]]

Template:DevDownload

2026-04-09T00:19:14Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=wesnoth-1.19.22-win64.exe |
hash=805a9da0b230f4334431704ba0cea6b8dcb4613da2530fcf1f315ff382ec67e2}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=Wesnoth_1.19.21.dmg |
hash=ef44157e1056fae915df935b8cb32af88d2072eaa8e8ac2c856a4d78d40e7fd9}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=wesnoth-1.19.22.tar.bz2 |
hash=dccf874092cf42dfbef61e30217f55d40ab4608532ff6dba3be7c052ca3e0c66}}

Template:StableDownload

2026-04-09T00:18:43Z

Pentarctagon:

<noinclude>
== Stable (1.18 branch) ==
</noinclude>
==== Windows (10 1903 and later, 64-bit only) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.7 | filename=wesnoth-1.18.7-win64.exe |
hash=1ebe433b8f7b526944b63d15caf11f42481375130431237b3f1139a517c7c7bb}}

==== macOS (10.12 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.6 | filename=Wesnoth_1.18.6.dmg |
hash=1b9a0ba71c11a386ea0daef357cb508f5c9dc792eed71eff1a3783c056214c93}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.7 | filename=wesnoth-1.18.7.tar.bz2 |
hash=d6b50cfdf4388954a1c3da66a61abacdc7643a17aa78a16196e16e720a661fc2}}

Template:DevDownload

2026-03-30T01:57:23Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=wesnoth-1.19.22-win64.exe |
hash=805a9da0b230f4334431704ba0cea6b8dcb4613da2530fcf1f315ff382ec67e2}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=wesnoth-1.19.21-win64.exe |
hash=7492d586fa192b5d60dfbc4265567e344993401aed6a63d03dc53db130cbbcbb}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=Wesnoth_1.19.21.dmg |
hash=ef44157e1056fae915df935b8cb32af88d2072eaa8e8ac2c856a4d78d40e7fd9}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.22 | filename=wesnoth-1.19.22.tar.bz2 |
hash=dccf874092cf42dfbef61e30217f55d40ab4608532ff6dba3be7c052ca3e0c66}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=wesnoth-1.19.21.tar.bz2 |
hash=d97521cda6717c0a76f3830d68e8918975ca88310e0f6d693db9b62c0585b16d}}

PblWML

2026-03-29T03:38:43Z

Pentarctagon: /* forum_auth */

{{WML Tags}}

To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.

See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.

Note: Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable. {{DevFeature1.15|4}} The translations in the .pbl-files are used, but they are used as a plain text instead of Gettext strings, so don't mark these strings as translatable.

== What goes into a .pbl file? ==

'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''

The following keys are recognized for .pbl files:

=== icon ===
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.

: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctions]] to recolor it. For example:

::icon="units/elves-wood/archer+female-sword-1.png~RC(magenta>brightorange)"
:or
::icon="units/human-peasants/peasant-ranged.png~RC(magenta>white)~CS(24,24,24)"
:or
::icon="units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)"

: Because the add-on manager's UI is dark, recoloring to light colors looks usually better. [https://irydacea.me/projects/wespal Wespal] is a tool that provides a convenient way to preview recolored unit sprites without needing to launch the game with specific WML or Lua edits.

: {{DevFeature1.13|12}} Instead of a standard Wesnoth image, a [[DataURI]] can also be used. This way, an image can be directly included into the _server.pbl file. Take care to leave no trailing newline.

=== title ===
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.
: '''This value is required'''.

=== version ===
: Displayed to the right of the title; it is merely text. However, starting with Wesnoth 1.6, the required format is '''x.y.z''' where '''x''', '''y''' and '''z''' are numbers — and a value for '''x''' greater than ''0'' implies the add-on is complete, feature-wise. Trailing non-numeric elements are allowed, but nothing should appear before or between these numbers. The string of numbers will be modified on the server by inserting or appending zeros as neccesary to meet the required format. All this is necessary for the “Update All” button to work correctly. ([[#Version Key Examples|See Examples]])
: '''This value is required'''.

=== author ===
: Displayed to the right of the version; it is merely text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.

: {{DevFeature1.17|3}} When using forum_auth, this value is a single forum account name which will have the ability to upload new versions of the add-on, delete the add-on from the add-ons server, and update the secondary_authors field.

: {{DevFeature1.19|7}} This value is now used the same as it was pre-forum_auth. It is only used to display in the addons manager.

: '''This value is required'''.

=== passphrase ===
: Not displayed. It prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''

: {{DevFeature1.15|12}}

: It is no longer required to keep the passphrase in the .pbl file at all. If it is not present, then Wesnoth will prompt for it to be entered when uploading or deleting an add-on.

=== description ===
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.
: '''This value is required'''.

=== dependencies ===
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])

=== tags ===
{{DevFeature1.13|12}}
: An optional string including a comma-separated list of keywords used for matching add-ons when typing terms into the Filter box on the top left of the Add-ons Manager. There are no specific requirements on the syntax of the keywords listed here, but a general recommendation is to keep them relevant for players. For example, one might include the add-on's acronym in the tags, the names or acronyms of add-ons to which it is related, and so on.

{{DevFeature1.15|13}} The in-game add-ons manager will show all the tags in the UI, and also includes a drop-down list of tags to filter by. Not all tags are listed in the filter box, and the exact list of tags supported may change before 1.16 is released, but the list is currently:

* '''cooperative''': All human players are on the same team, versus the AI
* '''cosmetic''': These make the game look different, without changing gameplay
* '''difficulty''': Can make campaigns easier or harder
* '''rng''': Modify the randomness in the combat mechanics, or remove it entirely
* '''survival''': Fight against waves of enemies
* '''terraforming''': Players can change the terrain

For example, if an A New Land style add-on had tags ''building'', ''terraforming'', ''anl'', ''city'', and ''survival'' then it would be shown if either ''Terraforming'' or ''Survival'' was selected in the drop-down; the other tags wouldn't affect the filtering.

=== core ===
{{DevFeature1.13|0}}
: An optional string defining the id of the core which the addon is designed for. Defaults to "''default''". Don't specify for an addon which is of type "''core''" itself. Note: DO NOT SET this unless you know why you need it! Giving it an invalid value can lead to mysterious errors with your campaign failing to load!

=== translate ===
: If set to ''true'', the add-on would have been sent to and updated with [[WesCamp|WesCamp-i18n]], if that project were still active. However, as WesCamp is no longer active, this no longer does anything.

: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.

: Note: WesCamp was abandoned in 2014. Instead, please refer to:
* [[GettextForWesnothDevelopers]]
* [[GettextForTranslators#For_add-ons]]
* forum thread: [https://r.wesnoth.org/t46366 Guide: Translating your UMC without WesCamp].

=== type ===
: Indicates the type of the add-on; used to filter listings in the downloads manager dialog. Acceptable values are:

:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}
:* ''campaign'': single player campaign.
:* ''scenario'': single player scenario.
:* ''campaign_sp_mp'': hybrid campaign.
:* ''era'': multiplayer era.
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.
:* ''map_pack'': multiplayer map-pack.
:* ''campaign_mp'': multiplayer campaign.
:* ''scenario_mp'': multiplayer scenario. (See the note below.)
:* ''mod_mp'': multiplayer modification ({{DevFeature1.13|11}} can also used for single-player modifications, although it's still called ''mod_mp'').
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc. Note: Shows as Resources, not Media, in the add-ons interface
:* ''other'': The type to use when no other type fits.
: '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.

: '''This value is required'''.

=== email ===
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.

: '''This value is required if forum_auth is not set to true'''.

=== forum_auth ===
{{DevFeature1.17|3}}
: When set to ''true'', you will be prompted for your forum password when uploading your add-on. The username(s) available to select will be populated from the '''author''' field (before 1.19.7) or the '''primary_authors''' field (1.19.7+). If the username dropdown is empty, make sure to confirm that either the '''author''' or '''primary_authors''' field is present and spelled correctly, depending on what version of Wesnoth you are running.

When set to true, the ''passphrase'' and ''email'' fields are also not required.

=== primary_authors ===
{{DevFeature1.19|7}}
: A comma-delimited list of forum accounts that are allowed to upload new versions of the add-on or delete the add-on from the add-ons server.

=== secondary_authors ===
: A comma-delimited list of forum accounts that are allowed to upload new versions of the add-on, but aren't allowed to delete the add-on.

=== [feedback] ===
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.

==== topic_id ====
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, this topic_id corresponds to the series of digits in the ''t=YYYYY'' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!

=== [translation] ===
{{DevFeature1.15|4}}
: Multiple [translation] tags can be used to provide the addon with a localized title and description to be seen in the addons manager. However, it should be noted that the declared translations won't influence the list of supported locales as it depends only on the presence of .mo and .po files for corresponding languages.

==== language ====
: The target language code for the translation. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/] . You can use either its contracted version (like ''sv'' for Swedish) or a more precise variety (like ''zh_CN'' or ''ca_ES@valencia'').
: '''This value is required'''.

==== title ====
: The translation of addon's title for the target language.
: '''This value is required'''.

==== description ====
: The translation of addon's description for the target language.

The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== Examples ==

=== Dependency Key Example ===

The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:

dependencies=Imperial_Era,Era_of_Myths

=== Version Key Examples ===

{{DevFeature1.17|13}} the schema validation rejects many of the '''good''' examples. https://github.com/wesnoth/wesnoth/issues/7396

The following are examples of '''good''' version values:

version="1.5"
version="0.11.4"
version="0.1.4beta"
version="1.5c"

The following are examples of '''bad''' version values:

version="Beta1.5"
version="Incomplete (0.3.4)"

In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.

Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.

0.5 < 1.0
1.5 < 1.5c
1.0 < 1.0.1
1.0c < 1.0.1a
1.0.1a < 1.0.1c
1.0 Final < 1.0.1 Beta

=== Example .pbl File ===

<syntaxhighlight lang=wml>
title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"
[feedback]
topic_id=12345
[/feedback]
# Note: the translation feature works on version 1.14.14, 1.15.4 and later only
[translation]
language="ru"
title="Моя Кампания"
description="Вам придётся завалить немало плохишей. Но пока что готова лишь первая карта."
[/translation]
[translation]
language="zh_CN"
title="我的竞选"
description="你会杀死很多坏人。但是只完成了第一张地图。(translated online)"
[/translation]
</syntaxhighlight>

== See Also ==

* [[IGNFileFormat]]
* [[FancyAddonIcons]]
* [[ReferenceWML]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

Template:DevDownload

2026-03-09T01:08:56Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=wesnoth-1.19.21-win64.exe |
hash=7492d586fa192b5d60dfbc4265567e344993401aed6a63d03dc53db130cbbcbb}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=wesnoth-1.19.20-win64.exe |
hash=c55a71350f5aab18074a5cc781bc66a56a29086624df85f4e155d5a1a4e966f9}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=Wesnoth_1.19.21.dmg |
hash=ef44157e1056fae915df935b8cb32af88d2072eaa8e8ac2c856a4d78d40e7fd9}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=Wesnoth_1.19.20.dmg |
hash=9a0df54edbbffb503f527a1b8007b7860eace3cfb9b94207c2ad21047171eb94}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.21 | filename=wesnoth-1.19.21.tar.bz2 |
hash=d97521cda6717c0a76f3830d68e8918975ca88310e0f6d693db9b62c0585b16d}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=wesnoth-1.19.20.tar.bz2 |
hash=48f883f8cd3ea008f9170aeaa9fb9ebb486202dd72f455ae131363fc3d164f8f}}

MultiplayerServerWML

2026-02-22T15:17:36Z

Pentarctagon: /* Game setup (the phase from creation to start) */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot or a server-side queue, false otherwise.
** '''queue_type''': Either "normal" or "server_preset".
** '''queue_id''': The ID of the queue this game is being created from.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

When there are enough players to start a game, the last player to join the queue is chosen as the host and their client is told to create the game with the provided settings. This skips the game creation screen and goes straight to the staging screen. The other players in the queue are then told to join that game using the normal [join] command:
* '''[create_game]'''
** '''queue_id''': The ID of the queue to create the game for.
** '''[game]'''
*** '''scenario''': The ID of the scenario to create the game for.
*** '''era''': The ID of the era to use.
*** '''fog''': Whether to have fog enabled.
*** '''shroud''': Whether to have shroud enabled.
*** '''village_gold''': How much gold each village provides.
*** '''village_support''': How much unit support each village provides
*** '''experience_modifier''': The experience modifier to use.
*** '''countdown''': Not currently used, set to false.
*** '''random_start_time''': Whether to start at a random time of day.
*** '''shuffle_sides''': Whether to shuffle the sides' starting positions.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

MultiplayerServerWML

2026-02-22T15:14:33Z

Pentarctagon: /* Queues */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot, false otherwise.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

When there are enough players to start a game, the last player to join the queue is chosen as the host and their client is told to create the game with the provided settings. This skips the game creation screen and goes straight to the staging screen. The other players in the queue are then told to join that game using the normal [join] command:
* '''[create_game]'''
** '''queue_id''': The ID of the queue to create the game for.
** '''[game]'''
*** '''scenario''': The ID of the scenario to create the game for.
*** '''era''': The ID of the era to use.
*** '''fog''': Whether to have fog enabled.
*** '''shroud''': Whether to have shroud enabled.
*** '''village_gold''': How much gold each village provides.
*** '''village_support''': How much unit support each village provides
*** '''experience_modifier''': The experience modifier to use.
*** '''countdown''': Not currently used, set to false.
*** '''random_start_time''': Whether to start at a random time of day.
*** '''shuffle_sides''': Whether to shuffle the sides' starting positions.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

MultiplayerServerWML

2026-02-22T15:13:08Z

Pentarctagon: /* Queues */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot, false otherwise.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

When there are enough players to start a game, the last player to join the queue is chosen as the host and their client is told to create the game with the provided settings. This skips the game creation screen and goes straight to the staging screen. The other players in the queue are then told to join that game:
* '''[create_game]'''
** '''queue_id''': The ID of the queue to create the game for.
** '''[game]'''
*** '''scenario''': The ID of the scenario to create the game for.
*** '''era''': The ID of the era to use.
*** '''fog''': Whether to have fog enabled.
*** '''shroud''': Whether to have shroud enabled.
*** '''village_gold''': How much gold each village provides.
*** '''village_support''': How much unit support each village provides
*** '''experience_modifier''': The experience modifier to use.
*** '''countdown''': Not currently used, set to false.
*** '''random_start_time''': Whether to start at a random time of day.
*** '''shuffle_sides''': Whether to shuffle the sides' starting positions.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

MultiplayerServerWML

2026-02-22T14:46:30Z

Pentarctagon: /* Queues */

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot, false otherwise.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby. Only used by add/update.
** '''players_required''': How many players are required before a game is started. Only used by add/update.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

MultiplayerServerWML

2026-02-22T14:46:00Z

Pentarctagon:

This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. Since 1.15+ client can also send 0x00 0x00 0x00 0x01 instead to request entire connection to be [https://github.com/wesnoth/wesnoth/blob/2f8136951cd77526188cf8d0fb2cf21eaa2ebe63/src/server/common/server_base.hpp#L60-L76 encapsulated in TLS] immediately '''after'''. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in '''big-endian''' (network byte order). Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.
*** '''client_source''': The client's distribution info. (Steam, SourceForge, App Store, etc.)

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
** or '''[reject]''' (if the version is unknown)
*** '''accepted_versions''': A comma-separated list of globs that this server does accept

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB). Since version 1.15+ if TLS was successfully established before then password will be passed as is, without hashing, relying on TLS for secrecy. Passing password hashes is no longer supported to free the client from responsibility to support all hash schemes the forum can potentially use. Client will emit error instead of trying to send password if TLS wasn't established.

* server response
** '''[join_lobby]'''
*** '''is_moderator''': "yes" if the user is a moderator, "no" otherwise.
*** '''profile_url_prefix''': The external URL prefix for player profiles (empty if the server doesn't have an attached database)
** or '''[error]''' (server is waiting for another '''[login]''' message now)
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''[slot_data]''' replaces '''slots''' since {{DevFeature1.13|12}}
***** '''max''': The number of total slots.
***** '''vacant''': The number of vacant slots.
**** '''turn''': The current turn/max turn.
**** '''[turn_data]''' replaces '''turn''' since {{DevFeature1.13|12}}
***** '''current''': The current turn number.
***** '''max''': The total number of turns.
**** '''[modification]''' Modifications used in this game. See [[ModificationWML]].
***** '''id''': ID of the modification.
***** '''name''': Name of the modification.
***** '''addon_id''': ID of the addon the modification is from.
***** '''require_modification''': A boolean value; if set to yes, all players have to have this modification installed to join the game.
**** '''[options]''' Options selected for this game. See [[OptionWML]].
***** '''[campaign|era|modification|multiplayer]'''
****** '''id''': ID of the addon the campaign|era|modification|multiplayer (scenario) is from.
****** '''[option]'''
******* '''id''': ID of the option.
******* '''value''': Value of the option.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in.
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.
** '''password_request''': This is a response to a login attempt. The client needs to send a password on another login attempt.
** '''force_confirmation''': Confirmation to login even if there is an existing client with the same name. If login is continued then that existing client is getting kicked.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.
* '''[refresh_lobby]''': Request the full gamelist.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.
** '''password''': The password to use to join the game.
** '''ignored''': The list of ignored players from the host.
** '''auto_hosted''': True if this request is from a bot, false otherwise.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game
** '''reason''': optional reason if sent by the server and was initiated by moderator action

== In-game communication ==

Normal scenario communication ([[ReplayWML]]):
* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a [[ReplayWML|replay]]: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

Multiplayer specific communication:
* '''[request_choice]'''
** '''request_id''': unique ID of the choice request
** '''[random_seed]''': client requests a random number (used for attacks for example)
** '''[change_controller_wml]''': change controller request from scenario WML
*** '''side''': side number
*** '''old_controller''': old [[SideWML#controller|controller]] value
*** '''new_controller''': new [[SideWML#controller|controller]] value
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

Client commands:
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

== Game history ==
This is a request to query a set of 11 rows of game history data based on the provided search criteria. The official client calls this from the Match History button in the multiplayer lobby to display 10 rows of data. The 11th row is used as a flag to indicate whether there is more data to be queried or not via the right/left arrows on the dialog.

* '''[game_history_request]'''
** '''offset''': where in the result set to start returning data from. If there are 50 results and offset 10 is given, then rows 10-21 will be returned.
** '''search_player''': the forum username of the player to search for.
** '''search_game_name''': the name of the game to filter results by. Can use the * (matches any character before or after it's used) and _ (matches any single character) wildcards.
** '''search_content_type''': the type of content to filter by. Must be one of:
*** '''0''': scenario
*** '''1''': era
*** '''2''':modification
** '''search_content''': The content to filter by. This is the ID of the content, not the name displayed on the UI, due to the translated name getting stored in the database.

== Queues ==
Queue info sent to the client on join or when the server's config is reloaded and the queue information has changed:
* '''[queue_update]'''
** '''queue_id''': The server's unique ID for the queue.
** '''action''': One of add/update/remove.
** '''display_name''': The text to show in the list of queues in the lobby.
** '''players_required''': How many players are required before a game is started.

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

== See also ==
[https://github.com/renom/fastbot fastbot] - the bot for tournaments which implements the protocol, can log in into the lobby and host games. Written in Go.
[[Category:WML Reference]]
[[Category:Server Documentation]]

Template:DevDownload

2026-02-05T00:41:55Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=wesnoth-1.19.20-win64.exe |
hash=c55a71350f5aab18074a5cc781bc66a56a29086624df85f4e155d5a1a4e966f9}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=wesnoth-1.19.19-win64.exe |
hash=1d2529daa2c585579176a88655133297b7e2b4ca634f45468bc2f13866604565}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=Wesnoth_1.19.20.dmg |
hash=9a0df54edbbffb503f527a1b8007b7860eace3cfb9b94207c2ad21047171eb94}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=Wesnoth_1.19.19.dmg |
hash=ac733dd52d01026448e7127b48eedfe69ad4b0d0c6089a367592c6d2d1c8d3fc}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=wesnoth-1.19.20.tar.bz2 |
hash=48f883f8cd3ea008f9170aeaa9fb9ebb486202dd72f455ae131363fc3d164f8f}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=wesnoth-1.19.19.tar.bz2 |
hash=d4fba3ecc1a92293f90d623edfef97be7ed6abe963bdcd7134de256fb6977c1d}}

Template:DevDownload

2026-02-01T17:57:57Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=wesnoth-1.19.20-win64.exe |
hash=c55a71350f5aab18074a5cc781bc66a56a29086624df85f4e155d5a1a4e966f9}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=wesnoth-1.19.19-win64.exe |
hash=1d2529daa2c585579176a88655133297b7e2b4ca634f45468bc2f13866604565}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=Wesnoth_1.19.19.dmg |
hash=ac733dd52d01026448e7127b48eedfe69ad4b0d0c6089a367592c6d2d1c8d3fc}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.18 | filename=Wesnoth_1.19.18.dmg |
hash=e3c7490086c6d4200c991e54e541eb830ce2252a453a10ce07dfc0913fd3df23}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.20 | filename=wesnoth-1.19.20.tar.bz2 |
hash=48f883f8cd3ea008f9170aeaa9fb9ebb486202dd72f455ae131363fc3d164f8f}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=wesnoth-1.19.19.tar.bz2 |
hash=d4fba3ecc1a92293f90d623edfef97be7ed6abe963bdcd7134de256fb6977c1d}}

Template:DevDownload

2025-12-31T01:45:23Z

Pentarctagon:

<noinclude>
== Development (1.19 branch) ==
</noinclude>
==== Windows (10 1903 and later) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=wesnoth-1.19.19-win64.exe |
hash=1d2529daa2c585579176a88655133297b7e2b4ca634f45468bc2f13866604565}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.18 | filename=wesnoth-1.19.18-win64.exe |
hash=3bea895b5ac6520af3c7217283afcc7e17eb96924c3859e559fd04adb35f6fe8}}

==== macOS (10.13 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=Wesnoth_1.19.19.dmg |
hash=ac733dd52d01026448e7127b48eedfe69ad4b0d0c6089a367592c6d2d1c8d3fc}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.18 | filename=Wesnoth_1.19.18.dmg |
hash=e3c7490086c6d4200c991e54e541eb830ce2252a453a10ce07dfc0913fd3df23}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.19 | filename=wesnoth-1.19.19.tar.bz2 |
hash=d4fba3ecc1a92293f90d623edfef97be7ed6abe963bdcd7134de256fb6977c1d}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth |
version=1.19.18 | filename=wesnoth-1.19.18.tar.bz2 |
hash=22c788998a7555def490ca559844a8721029e25a5529d8584dfbc15f2a579b72}}

Template:StableDownload

2025-12-31T01:19:29Z

Pentarctagon:

<noinclude>
== Stable (1.18 branch) ==
</noinclude>
==== Windows (10 1903 and later, 64-bit only) {{{4|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.6 | filename=wesnoth-1.18.6-win64.exe |
hash=7365efdc70c127f6d0bfbc6a8f976e6cba1eec59f2bbfb6dc27644534670b162}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.5 | filename=wesnoth-1.18.5-win64.exe |
hash=915d9c0374221782fbfaecd3ac8d8833b470c6ed6c059e6086d5082a28edf80f}}

==== macOS (10.12 and later) {{{5|}}} ====
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.6 | filename=Wesnoth_1.18.6.dmg |
hash=1b9a0ba71c11a386ea0daef357cb508f5c9dc792eed71eff1a3783c056214c93}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.5 | filename=Wesnoth_1.18.5.dmg |
hash=73e34ee58a7c81055bdf94f1b0646a524a992235682ce227fb8d3829af4061f1}}

==== Source code ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - How to compile the source code
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.6 | filename=wesnoth-1.18.6.tar.bz2 |
hash=6bb8b17854c974bc66cb7a2574a53fe9efb4d2c138bb1373032e57788204985e}}
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.18 |
version=1.18.5 | filename=wesnoth-1.18.5.tar.bz2 |
hash=e15db3caf446d91d389fc275f10c1a9e7ca3c6176c3b8ce94f5ee4a7a0c81bd6}}