BuildingCampaignsThePBLFile
From Wesnoth
The PBL file is one of the three elements of an unofficial (non-mainline) campaign (the other two are the campaign.cfg file and campaign folder). It is an ASCII text file that has the same name as the campaign.cfg file, except the extension is .pbl. Full documentation is found at PblWML.
Click here for an example of what we're talking about.
The PBL file is used by the campaign server. It lets you publish, update, and delete your campaign on the server. As the campaign creator, you will be the only one with access to the PBL file, and likewise without it you cannot manage your campaign on the campaign server.
The campaign server is a game feature for version 0.8.5 and later. It is integrated into the game. To access the campaign server, run "The Battle for Wesnoth", select "Get Addons", which leads directly to the server.
The server uses a custom protocol and does not allow http/ftp/ssh access.
The PBL file contains the following tags:
author=" "
title=" "
icon=" "
version=" "
description=" "
type=" "
The next tag is optional. It is randomly generated by the server the first time you publish the campaign if you don't supply a passphrase. The next time you view the PBL file you will see it added for you. If you delete this, you will no longer be able to manage (update/delete) your campaign, and you'll have to beg Ivanovic to fix it, by sending him a personal message in the forums.
passphrase=" "
It is recommended that you provide a way for contacting in case the admins have trouble with your add-ons, for example, if the server crashes and the content should be re-uploaded. Use the next tag in your .pbl file for providing your email address. Note that it will not be revealed to clients.
email=" "
PBL Tag notes:
- author: indicates name of the author of the add-on. Also if several people work on the campaign you should list all of the significant contributors here and perhaps describe what each person was responsible for.
- icon: should be the filename of any standard image accessible by the campaign server from the images directory. You will not have access to custom images in your campaign. Be sure to use forward slashes (/), not back slashes (\), as a file separator as that is what the game expects. After you have uploaded your campaign, you should verify that the icon is displayed on the campaign download page. An example is "items/lighthouse.png". If the icon is a unit with magenta color, please use ImagePathFunctionWML to team-color it.
- version: can be any text. The recommend format is x.y.z where x, y and z are numbers. Previously version often referred to the version Wesnoth needed. However now that the 1.0 release has occured that is no longer desired. A version number of 1.0 or greater indicates the campaign is complete in that all scenarios are present and it is nominally balanced.
- description: is not currently displayed on the client, but is shown on the web interface to the campaign server. You can use it to provide a brief description of what the campaign is about and for pre 1.0 releases give people an idea of how complete it is.
- If the title keyword is not set, the campaign.cfg filename will be displayed as the campaign name by the campaign server. In this case underscores (_) will be replaced by spaces in the displayed name and the suffix (.cfg) dropped. However, you should supply a title.
- translate: (optional) if the value is true the campaign is marked to be translated and will automatically be uploaded to wescamp (this functionality is fully operational yet)
- Technically, you can specify a passphrase before uploading for the first time, but it's simpler to leave it out. The benefit of specifying a passphrase is that you probably won't forget it.
- email: the electronic mail address of the author/maintainer of the add-on. It is available only to server administrators to contact content submitters.
- type: the type of the add-on for classifying it in 1.5.0 and later clients. See PblWML for details.
- Warning: Do not mark the strings in the .pbl file as translatable. This causes problems and can never work. Similarly, you cannot use preprocessor macros or includes in this file, since they are not preprocessed at all.