Difference between revisions of "CampaignServerWML"

From The Battle for Wesnoth Wiki
(→‎See Also)
m (minor wikification)
 
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
= Campaign Server WML =
+
<div class="tright"> __TOC__ </div>
  
−
This page describes the WML commands exchanged between campaign download clients and a campaign server.  
+
This page describes the WML commands exchanged between the add-ons server (<b>[[campaignd]]</b>) and clients.
  
−
== Listing Available Campaigns ==
+
For historical reasons, both the server software's name and the WML tags which are part of its communication protocol make exclusive reference to "campaigns" instead of "add-ons". However, in practice there is no real difference between any kind of add-ons as far as the server is concerned.
  
−
This request is used to retrieve a list of campaigns available on the server and some overview information about them.
+
== Common responses ==
  
−
* Request
+
These are WML messages sent by the server in response to any of the commands listed below.
−
** '''[request_campaign_list]'''
 
−
*** '''after''': only select campaigns last updated after the indicated time. ''after'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated after Mon Oct 10 21:42:41 2005 GMT, you could not specify a value for ''times_relative_to'' (to use the default of relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]) and specify ''after'' = "1128980561".
 
−
*** '''before''': only select campaigns last updated before the indicated time. ''before'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated over a day ago, you could specify ''times_relative_to'' = "now" and ''before'' = "-86400".
 
−
*** '''language''': return information only about campaigns that appear to be translated into this language. These names will normally be POSIX locale names. Typically you will want to either use a two letter language code (e.g. "de") or a two letter language code followed by a two character region code (e.g. "pt_BR"). Note that "pt" will not match "pt_BR".
 
−
*** '''name''': return information for this campaign. If the name is specified and not the empty string then only information about campaigns with matching names (unless something changes there will be at most one such campaign) will be returned.
 
−
*** '''times_relative_to''': "now" means that ''before'' and ''after'' are in seconds relative to the time when the request is processed by the campaign server. Any other value, or if it is not set, indicates that ''before'' and ''after'' are in seconds relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch].
 
−
* Response
 
−
** '''timestamp''': what time the campaign server thought it was when this response was generated. You shouldn't count on this as a guaranty that no new campaigns will appear with previous update times. This could be used to detect significant clock skew or possibly used as an approximate time for how far you need to look back for updated campaigns.
 
−
** '''[campaigns]'''
 
−
*** '''[campaign]'''
 
−
**** '''author''': author(s) of the campaign.
 
−
**** '''dependencies''': list of add-on dependencies
 
−
**** ''description'': (current trunk only) description of the campaign. For pre 1.0 campaigns this should also describe the playability.
 
−
**** '''downloads''': the number times the campaign (including previous versions) has been downloaded directly from the campaign server.
 
−
**** '''filename''': filename campaign is stored in (currently the same as ''name'').
 
−
**** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
 
−
**** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
 
−
**** '''size''': the size of the campaign in bytes on the campaign server.
 
−
**** '''timestamp''': when this version of the campaign was uploaded.
 
−
**** '''title''': campaign title. This is not a translatable string.
 
−
**** '''translate''': whether the campaign will be automatically send to wescamp and updated from wescamp.
 
−
**** '''uploads''': number of uploads (initial upload gets 1)
 
−
**** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
 
−
**** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
 
−
**** '''[translation]'''
 
−
***** '''language''': a language that this campaign has appeared to have been at least partially translated into. The following heuristic is used when a campaign is uploaded to extract a list of languages. The list of directories in the uploaded campaign is recursively searched. If a directory named 'LC_MESSAGES' is found then the name of the object containing this '''[dir]''' (normally the parent directory, but could be the campaign name if someone did something silly) is added to the list of translations. Directories named "LC_MESSAGES" are not searched for further matches. The normal naming convention is to use Posix locale names. This will usually be a two letter language code (e.g. "de") or a two letter language code followed by a two letter region code (e.g. "pt_BR"). Since "en_US" is the base language, this language will not be listed as an available translation.
 
  
−
== Downloading a Campaign ==
+
=== [message]: Informational messages ===
  
−
This command is used to download a specified campaign from the campaign server.
+
This response is typically sent to confirm that an operation succeeded.
  
−
* Request
+
* '''[message]'''
−
** '''[request_campaign]'''
+
** '''message''': String containing a message for the client to display to the user.
−
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
 
−
* Response
 
−
** '''author''': author(s) of the campaign.
 
−
** '''campaign_name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
 
−
** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
 
−
** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
 
−
** '''name''': this field will always be empty. Client code would treat it as a directory name if it was not empty.
 
−
** '''timestamp''': the time the campaign was last uploaded to the campaign server. This is a decimal string containing the number of seconds since the unix epoch.
 
−
** '''title''': the title of the campaign. This is not a translatable string.
 
−
** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
 
−
** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
 
−
** '''[file]'''
 
−
*** '''name''': the name of the file. This does not include any path information.
 
−
*** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
 
−
** '''[dir]'''
 
−
*** '''name''': the name of the directory. This does not include any path information.
 
−
*** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).
 
  
−
== Uploading a Campaign ==
+
=== [error]: Error messages ===
  
−
This command is used to upload a new or updated version of an add on campaign to the campaign server.
+
This response is sent when an operation has failed for any reason, whether it be a user error or an issue with the server. It is also sent upon receiving an unrecognized request.
  
−
* Request
+
* '''[error]'''
−
** '''[upload]'''
+
** '''message''': String containing an error message for the client to display to the user.
−
*** '''author''': author(s) of the campaign.
+
** '''extra_data''': String containing additional information for the client to display. This is often a log of some kind (such a list of illegal filenames found during an upload request), so a client should be prepared for this to be an overlong string that might not completely fit in the screen.
−
*** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
 
−
*** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
 
−
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
 
−
*** '''passphrase''': this is used to control updates to campaigns on the server. For existing campaigns, if the passphrase doesn't match, the update will be rejected. You can't easily change the passphrase yourself. If you lose or need to change the passphrase you need to contact the server administrator.
 
−
*** '''email''': it is used by campaign server administrators to contact authors in case of important problems with their add-ons (incompatibilities, broken data files, violation of server [[Distributing_content#License|policies]], etc.).
 
−
*** '''title''': the title of the campaign. This is not a translatable string.
 
−
*** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
 
−
*** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
 
−
*** '''[data]'''
 
−
**** '''[file]'''
 
−
***** '''name''': the name of the file. This does not include any path information.
 
−
***** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
 
−
**** '''[dir]'''
 
−
***** '''name''': the name of the directory. This does not include any path information.
 
−
***** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).
 
−
* Response
 
−
** '''[message]'''
 
−
*** '''message''': translatable string that indicates that the campaign upload was successful.
 
  
−
== Changing the Passphrase for a Campaign ==
+
== Archive format ==
  
−
This command is used to change the passphrase for a campaign. Currently the normal client doesn't have a way to use this. However, you can use the perl script campaign_passphrase.pl to do it, if you have a copy of the source tree.
+
'''[upload]''' and '''[request_campaign]''' both use WML to describe archives containing the directory structure and files for each add-on. The archive format supports only regular files and directories, and file contents need to be encoded in a special fashion so that they can be serialized as WML for network transfers and disk storage.
  
−
* Request
+
Binary data cannot contain null characters, as well as certain special characters. In order to build escape sequences for them, a single-byte value of <code>0x01</code> is used followed by the actual byte value incremented by 1. For example, the byte sequence <code>0x01 0x01</code> is used to represent the null character <code>0x00</code>, and <code>0x01 0xFF</code> represents the special character <code>0xFE</code>.
−
** '''[change_passphrase]'''
 
−
*** '''name''': The name of campaign.
 
−
*** '''passphrase''': The old passphrase.
 
−
*** '''new_passphrase''': The new passphrase.
 
−
* Respose
 
−
** '''[message]'''
 
−
*** '''message''': Translatable string that says that the passphrase was changed.
 
  
−
== Deleting a Campaign ==
+
As of Wesnoth 1.14, the following byte values need to be escaped:
  
−
This command is used to delete an existing campaign from the campaign server.
+
<code>0x00</code> (null character), <code>0x01</code> (escape character), <code>0x0D</code> (carriage return), <code>0xFE</code> (used by the WML parser to encode <code>\xFEline</code> and <code>\xFEtextdomain</code> directives).
  
−
* Request
+
=== [file]: Regular file ===
−
** '''[delete]'''
 
−
*** '''name''': The name of the campaign to delete.
 
−
*** '''passphrase''': This must match the passphrase on record for the campaign or the master_password in order for the campaign to be deleted. Master_password.
 
−
* Response
 
−
** '''[message]'''
 
−
*** '''message''': Translatable string that says that the campaign was deleted.
 
  
−
== Request License Information ==
+
* '''name''': Filename (not a relative or absolute path).
 +
* '''contents''': The contents of a file encoded as binary data as described above.
  
−
Retrieve the terms of the license used for any uploaded campaigns. You may not upload a campaign if you don't (or can't) aggree to the license. Wesnoth requires campaigns (including images and sound) to be licensed under the GPL. For more information on licensing, see [[Wesnoth:Copyrights]].
+
=== [dir]: Directory ===
  
−
* Request
+
* '''name''': Directory name (not a relative or absolute path).
−
** '''[request_terms]'''
+
* '''[file]''', '''[dir]''': Regular files and subdirectories under this directory. The syntax for '''[dir]''' is recursive.
−
* Response
 
−
** '''[message]'''
 
−
*** '''message''': translatable string containing the text of the license.
 
  
−
== Developer commands ==
+
== [request_campaign_list]: Listing server contents ==
  
−
* Request
+
This request is used to retrieve a list of add-ons available on the server and some overview information about them.
−
** '''[validate_scripts]'''
+
 
−
*** '''name''': The name of the campaign to sign.
+
There are a few attributes both in the request and response WML that use timestamps. These are expected to be in secodns relative
−
*** '''master_password''': The signing password.
+
 
−
* Response
+
=== Request ===
−
** '''[message]'''
+
 
−
*** '''message''': Translatable(?) string that says that the campaign was signed.
+
* '''[request_campaign_list]'''
 +
** '''name''': If specified and not empty, return information only for a single add-on matching this name.
 +
** '''language''': Return information only about add-ons that appear to be translated into this language. These names will normally be POSIX locale names. Typically you will want to either use a two letter language code (e.g. <code>de</code>) or a two letter language code followed by a two character region code (e.g. <code>pt_BR</code>). Note that <code>pt</code> will not match <code>pt_BR</code>.
 +
** '''times_relative_to''': <code>now</code> means that '''before''' and '''after''' below are understood to be measured in seconds relative to the time when the request is processed by campaignd. If unset or set to any other value, '''before''' and '''after''' are assumed to be in seconds relative to the [https://en.wikipedia.org/wiki/Unix_epoch Unix epoch].
 +
** '''after''': Only select add-ons last updated after the indicated time. For example, to select add-ons last updated after Mon Oct 10 21:42:41 2005 UTC, you could leave '''times_relative_to''' unset and specify <syntaxhighlight lang="wml" inline>after=1128980561</syntaxhighlight>.
 +
** '''before''': Only select add-ons last updated before the indicated time. For example, to select add-ons last updated over a day ago, you could specify <syntaxhighlight lang="wml" inline>times_relative_to="now"</syntaxhighlight> and <syntaxhighlight lang="wml" inline>before=-86400</syntaxhighlight>.
 +
 
 +
=== Response ===
 +
 
 +
* '''timestamp''': The time in seconds relative to the [https://en.wikipedia.org/wiki/Unix_epoch Unix epoch] that the add-ons server reported when generating the response. You shouldn't count on this as a guarantee that no new add-ons will appear with previous update times. This could be used to detect significant clock skew or possibly used as an approximate time for how far you need to look back for updated campaigns.
 +
* '''[campaigns]'''
 +
** '''[campaign]'''
 +
*** '''author''', '''dependencies''', '''description''', '''icon''', '''tags''', '''title''', '''translate''', '''type''', '''version''': See [[PblWML]].
 +
*** '''downloads''': The number of times the add-on (including previous versions) has been downloaded directly from the add-ons server. This does not include updates, which are handled by the official clients using the '''increase_downloads''' option to avoid bumping the downloads count; nor does it include downloads from the add-ons server web, which is handled by the web server independently.
 +
*** '''feedback_url''': URL to the add-on's feedback URL specified by the author in the [[PblWML#.5Bfeedback.5D|pbl [feedback] tag]] and formatted according to the server's own rules. For the current add-ons server, this is a forum thread URL in the format <code><nowiki>https://r.wesnoth.org/t<TOPIC_ID></nowiki></code>.
 +
*** '''filename''': The name of the file used to store the add-on archive on the server (currently the same as '''name''').
 +
*** '''name''': The name of the add-on. Note this is not the title and shouldn't have spaces in it. This corresponds to the add-on directory name on the client side.
 +
*** '''original_timestamp''': When the first version of the add-on was uploaded. If the add-on was previously deleted from the server, this will be the time of the first reupload after the last deletion.
 +
*** '''size''': The on-disk size of the add-on pack in bytes on the server. If the add-on pack is stored in a compressed format, this will be the compressed size, not the uncompressed size. Because the network format currently used to send the file uses the same compression and nearly identical structure, this also happens to be almost exactly the same size transferred over the network when downloading the add-on.
 +
*** '''timestamp''': When the current version of the add-on was uploaded.
 +
*** '''uploads''': Number of uploads, including the initial upload.
 +
*** '''[translation]'''
 +
**** '''language''': The name of a locale that this add-on appears to have been at least partially translated into. The following heuristic is used when an add-on is uploaded to extract a list of languages:<br>The list of directories in the uploaded campaign is recursively searched. If a directory named <code>LC_MESSAGES</code> is found then the name of the object containing this '''[dir]''' (normally the parent directory, but could be the add-on name if someone did something silly) is added to the list of translations. Directories named <code>LC_MESSAGES</code> are not searched for further matches.<br>The normal naming convention is to use POSIX locale names. This will usually be a two letter language code (e.g. <code>de</code>) or a two letter language code followed by a two letter region code (e.g. <code>pt_BR</code>). Since <code>en_US</code> is the base language, this language will not be listed as an available translation. {{DevFeature1.15|4}} If the server finds translation files, but the translation tag is absent, it will be created but without additional data other than a supported=yes attribute.
 +
**** '''supported''': {{DevFeature1.15|4}} Is set to ''true'' if the corresponding .po or .mo localization file is found, ''false'' otherwise. Defaults to ''true'' in older addons to ensure backwards-compatibility.
 +
**** '''title''': {{DevFeature1.15|4}} The translated title of the addon.
 +
**** '''description''': {{DevFeature1.15|4}} The translated description of the addon.
 +
 
 +
== [request_campaign]: Downloading an add-on ==
 +
 
 +
This command is used to download the specified add-on from the server.
 +
 
 +
=== Request ===
 +
 
 +
* '''[request_campaign]'''
 +
** '''name''': The name of the add-on. Note this is not the user-visible title and should not have spaces in it.
 +
** '''increase_downloads''': A boolean value specifying whether the download counter for the add-on should be increased or not. The game's built-in add-ons client sets this to ''false'' when downloading updates for already installed add-ons.
 +
 
 +
=== Response ===
 +
 
 +
* '''author''', '''description''', '''icon''', '''tags''', '''title''', '''type''', '''version''': See [[PblWML]].
 +
* '''campaign_name''': The name of the add-on. Note this is not the title and shouldn't have spaces in it. This corresponds to the add-on directory name on the client side.
 +
* '''name''': This field will always be empty. Client code would treat it as a directory name if it were not empty.
 +
* '''original_timestamp''': When the first version of the add-on was uploaded. If the add-on was previously deleted from the server, this will be the time of the first reupload after the last deletion.
 +
* '''timestamp''': When the current version of the add-on was uploaded.
 +
* '''[file]''', '''[dir]''': See [[#Archive format|archive format]].
 +
 
 +
== [upload]: Uploading an add-on ==
 +
 
 +
This command is used to upload a new add-on or an updated version of an existing one to the server.
 +
 
 +
=== Request ===
 +
 
 +
* '''[upload]'''
 +
** See tags and attributes listed in [[PblWML]].
 +
** '''[data]'''
 +
*** '''[file]''', '''[dir]''': See [[#Archive format|archive format]].
 +
 
 +
=== Response ===
 +
 
 +
See [[#Common responses|Common responses]].
 +
 
 +
== [change_passphrase]: Changing a passphrase ==
 +
 
 +
This command is used to change the passphrase for an add-on. Currently the game does not have a user interface to make use of this function. However, the Python-based <code class="noframe">wesnoth_addon_manager</code> client included under <code class="noframe">data/tools</code> has a <code>--change-passphrase</code> switch that accomplishes the same purpose.
 +
 
 +
=== Request ===
 +
 
 +
* '''[change_passphrase]'''
 +
** '''name''': The name of the add-on.
 +
** '''passphrase''': The old passphrase.
 +
** '''new_passphrase''': The new passphrase.
 +
 
 +
=== Response ===
 +
 
 +
See [[#Common responses|Common responses]]. The <code>[message]</code> response confirms a successful passphrase change.
 +
 
 +
== [delete]: Deleting an add-on ==
 +
 
 +
This command is used to delete an existing add-on from the server.
 +
 
 +
=== Request ===
 +
 
 +
* '''[delete]'''
 +
** '''name''': The name of the add-on to delete.
 +
** '''passphrase''': The passphrase for the add-on. It must match the passphrase on record in order for the operation to succeed.
 +
** '''uploader''': The name of the author who uploaded the add-on. Required only for add-ons using forum_auth.
 +
 
 +
=== Response ===
 +
 
 +
See [[#Common responses|Common responses]]. The <code>[message]</code> response confirms the successful deletion of the add-on.
 +
 
 +
== [request_terms]: Requesting upload terms ==
 +
 
 +
Retrieves the upload terms that users must accept before uploading add-ons to the server. Wesnoth.org requires add-ons be licensed under the GNU GPL v2 or later, with assets allowed to be licensed under the same license or a Creative Commons license.  See [[Wesnoth:Copyrights]] for more information.
 +
 
 +
This action never fails.
 +
 
 +
=== Request ===
 +
* '''[request_terms]'''
 +
 
 +
=== Response ===
 +
 
 +
See [[#Common responses|Common responses]]. The <code>[message]</code> response contains the upload terms.
  
 
== See Also ==
 
== See Also ==
  
−
* [[UserScenarios#Campaign_Server_Web_Access]]
+
* [[Guide_to_UMC_Content]]
 
* [[PblWML]]
 
* [[PblWML]]
  
 
[[Category:WML Reference]]
 
[[Category:WML Reference]]
 +
[[Category:Server Documentation]]

Latest revision as of 15:14, 7 April 2023

This page describes the WML commands exchanged between the add-ons server (campaignd) and clients.

For historical reasons, both the server software's name and the WML tags which are part of its communication protocol make exclusive reference to "campaigns" instead of "add-ons". However, in practice there is no real difference between any kind of add-ons as far as the server is concerned.

Common responses

These are WML messages sent by the server in response to any of the commands listed below.

[message]: Informational messages

This response is typically sent to confirm that an operation succeeded.

  • [message]
    • message: String containing a message for the client to display to the user.

[error]: Error messages

This response is sent when an operation has failed for any reason, whether it be a user error or an issue with the server. It is also sent upon receiving an unrecognized request.

  • [error]
    • message: String containing an error message for the client to display to the user.
    • extra_data: String containing additional information for the client to display. This is often a log of some kind (such a list of illegal filenames found during an upload request), so a client should be prepared for this to be an overlong string that might not completely fit in the screen.

Archive format

[upload] and [request_campaign] both use WML to describe archives containing the directory structure and files for each add-on. The archive format supports only regular files and directories, and file contents need to be encoded in a special fashion so that they can be serialized as WML for network transfers and disk storage.

Binary data cannot contain null characters, as well as certain special characters. In order to build escape sequences for them, a single-byte value of 0x01 is used followed by the actual byte value incremented by 1. For example, the byte sequence 0x01 0x01 is used to represent the null character 0x00, and 0x01 0xFF represents the special character 0xFE.

As of Wesnoth 1.14, the following byte values need to be escaped:

0x00 (null character), 0x01 (escape character), 0x0D (carriage return), 0xFE (used by the WML parser to encode \xFEline and \xFEtextdomain directives).

[file]: Regular file

  • name: Filename (not a relative or absolute path).
  • contents: The contents of a file encoded as binary data as described above.

[dir]: Directory

  • name: Directory name (not a relative or absolute path).
  • [file], [dir]: Regular files and subdirectories under this directory. The syntax for [dir] is recursive.

[request_campaign_list]: Listing server contents

This request is used to retrieve a list of add-ons available on the server and some overview information about them.

There are a few attributes both in the request and response WML that use timestamps. These are expected to be in secodns relative

Request

  • [request_campaign_list]
    • name: If specified and not empty, return information only for a single add-on matching this name.
    • language: Return information only about add-ons that appear to be translated into this language. These names will normally be POSIX locale names. Typically you will want to either use a two letter language code (e.g. de) or a two letter language code followed by a two character region code (e.g. pt_BR). Note that pt will not match pt_BR.
    • times_relative_to: now means that before and after below are understood to be measured in seconds relative to the time when the request is processed by campaignd. If unset or set to any other value, before and after are assumed to be in seconds relative to the Unix epoch.
    • after: Only select add-ons last updated after the indicated time. For example, to select add-ons last updated after Mon Oct 10 21:42:41 2005 UTC, you could leave times_relative_to unset and specify after=1128980561.
    • before: Only select add-ons last updated before the indicated time. For example, to select add-ons last updated over a day ago, you could specify times_relative_to="now" and before=-86400.

Response

  • timestamp: The time in seconds relative to the Unix epoch that the add-ons server reported when generating the response. You shouldn't count on this as a guarantee that no new add-ons will appear with previous update times. This could be used to detect significant clock skew or possibly used as an approximate time for how far you need to look back for updated campaigns.
  • [campaigns]
    • [campaign]
      • author, dependencies, description, icon, tags, title, translate, type, version: See PblWML.
      • downloads: The number of times the add-on (including previous versions) has been downloaded directly from the add-ons server. This does not include updates, which are handled by the official clients using the increase_downloads option to avoid bumping the downloads count; nor does it include downloads from the add-ons server web, which is handled by the web server independently.
      • feedback_url: URL to the add-on's feedback URL specified by the author in the pbl [feedback] tag and formatted according to the server's own rules. For the current add-ons server, this is a forum thread URL in the format https://r.wesnoth.org/t<TOPIC_ID>.
      • filename: The name of the file used to store the add-on archive on the server (currently the same as name).
      • name: The name of the add-on. Note this is not the title and shouldn't have spaces in it. This corresponds to the add-on directory name on the client side.
      • original_timestamp: When the first version of the add-on was uploaded. If the add-on was previously deleted from the server, this will be the time of the first reupload after the last deletion.
      • size: The on-disk size of the add-on pack in bytes on the server. If the add-on pack is stored in a compressed format, this will be the compressed size, not the uncompressed size. Because the network format currently used to send the file uses the same compression and nearly identical structure, this also happens to be almost exactly the same size transferred over the network when downloading the add-on.
      • timestamp: When the current version of the add-on was uploaded.
      • uploads: Number of uploads, including the initial upload.
      • [translation]
        • language: The name of a locale that this add-on appears to have been at least partially translated into. The following heuristic is used when an add-on is uploaded to extract a list of languages:
          The list of directories in the uploaded campaign is recursively searched. If a directory named LC_MESSAGES is found then the name of the object containing this [dir] (normally the parent directory, but could be the add-on name if someone did something silly) is added to the list of translations. Directories named LC_MESSAGES are not searched for further matches.
          The normal naming convention is to use POSIX locale names. This will usually be a two letter language code (e.g. de) or a two letter language code followed by a two letter region code (e.g. pt_BR). Since en_US is the base language, this language will not be listed as an available translation. (Version 1.15.4 and later only) If the server finds translation files, but the translation tag is absent, it will be created but without additional data other than a supported=yes attribute.
        • supported: (Version 1.15.4 and later only) Is set to true if the corresponding .po or .mo localization file is found, false otherwise. Defaults to true in older addons to ensure backwards-compatibility.
        • title: (Version 1.15.4 and later only) The translated title of the addon.
        • description: (Version 1.15.4 and later only) The translated description of the addon.

[request_campaign]: Downloading an add-on

This command is used to download the specified add-on from the server.

Request

  • [request_campaign]
    • name: The name of the add-on. Note this is not the user-visible title and should not have spaces in it.
    • increase_downloads: A boolean value specifying whether the download counter for the add-on should be increased or not. The game's built-in add-ons client sets this to false when downloading updates for already installed add-ons.

Response

  • author, description, icon, tags, title, type, version: See PblWML.
  • campaign_name: The name of the add-on. Note this is not the title and shouldn't have spaces in it. This corresponds to the add-on directory name on the client side.
  • name: This field will always be empty. Client code would treat it as a directory name if it were not empty.
  • original_timestamp: When the first version of the add-on was uploaded. If the add-on was previously deleted from the server, this will be the time of the first reupload after the last deletion.
  • timestamp: When the current version of the add-on was uploaded.
  • [file], [dir]: See archive format.

[upload]: Uploading an add-on

This command is used to upload a new add-on or an updated version of an existing one to the server.

Request

Response

See Common responses.

[change_passphrase]: Changing a passphrase

This command is used to change the passphrase for an add-on. Currently the game does not have a user interface to make use of this function. However, the Python-based wesnoth_addon_manager client included under data/tools has a --change-passphrase switch that accomplishes the same purpose.

Request

  • [change_passphrase]
    • name: The name of the add-on.
    • passphrase: The old passphrase.
    • new_passphrase: The new passphrase.

Response

See Common responses. The [message] response confirms a successful passphrase change.

[delete]: Deleting an add-on

This command is used to delete an existing add-on from the server.

Request

  • [delete]
    • name: The name of the add-on to delete.
    • passphrase: The passphrase for the add-on. It must match the passphrase on record in order for the operation to succeed.
    • uploader: The name of the author who uploaded the add-on. Required only for add-ons using forum_auth.

Response

See Common responses. The [message] response confirms the successful deletion of the add-on.

[request_terms]: Requesting upload terms

Retrieves the upload terms that users must accept before uploading add-ons to the server. Wesnoth.org requires add-ons be licensed under the GNU GPL v2 or later, with assets allowed to be licensed under the same license or a Creative Commons license. See Wesnoth:Copyrights for more information.

This action never fails.

Request

  • [request_terms]

Response

See Common responses. The [message] response contains the upload terms.

See Also

Retrieved from "https://wiki.wesnoth.org/index.php?title=CampaignServerWML&oldid=70760"
This page was last edited on 7 April 2023, at 15:14.