PblWML

[edit]WML Tags

A: abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B: base_unit, background_layer, berserk, binary_path, break, brush;

C: campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D: damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E: editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F: facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G: game_config, get_global_variable, goal, gold, gold_carryover;

H: harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I: idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J: jamming_costs, join;

K: kill, killed;

L: label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M: male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N: not, note;

O: object, objective, objectives, on_undo, open_help, option, options, or;

P: part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R: race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S: save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T: target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U: unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V: value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W: while, wml_message, wml_schema;

Z: zoom;

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. (Version 1.15.4 and later only) 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. 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.

(Version 1.13.12 and later only) 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. (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.

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.

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!

(Version 1.15.12 and later only)

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. (See Example)

tags

(Version 1.13.12 and later only)

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.

(Version 1.15.13 and later only) 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

(Version 1.13.0 and later only)

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-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 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: 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. (Version 1.13.0 and later only)
• 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 ((Version 1.13.11 and later only) 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

(Version 1.17.3 and later only)

When set to true, you will be prompted for your forum username and password when uploading your add-on. When set to true, the passphrase and email fields are also not required.

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 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 http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!

[translation]

(Version 1.15.4 and later only)

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 [1] . 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

(Version 1.17.13 and later only) 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

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]

See Also

• IGNFileFormat
• FancyAddonIcons
• ReferenceWML
• CampaignServerWML