Difference between revisions of "PblWML"

From The Battle for Wesnoth Wiki
(What goes into a .pbl file?)
(Added examples section, added warning about version numbrers.)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== .pbl files ==
 
  
=== What is a .pbl file? ===
 
 
To upload a campaign you have made, you need a .pbl file.
 
To upload a campaign you have made, you need a .pbl file.
  
Line 14: Line 12:
 
Be aware that translations in the .pbl-files are '''not''' working, so don't mark these strings translateable.
 
Be aware that translations in the .pbl-files are '''not''' working, so don't mark these strings translateable.
  
=== What goes into a .pbl file? ===
+
== What goes into a .pbl file? ==
  
'''Note: ''You should ''not'' use special formatting or coloring in any fields when uploading to the official server.'''''
+
'''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:
 
The following keys are recognized for .pbl files:
  
* '''icon''': An image, displayed leftmost on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see [[CampaignWML]].) If the icon is a unit with magenta color, please use [[ImagePathFunctionWML]] to team-color it.
+
=== icon ===
 +
: An image, displayed leftmost on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see [[CampaignWML]].) If the icon is a unit with magenta color, please use [[ImagePathFunctionWML]] to team-color it.
  
* '''title''': Displayed to the right of the icon, it is just text. It should usually be the same as the name of your campaign when it is played.
+
=== title ===
 +
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your campaign when it is played.
  
* '''version''': Displayed to the right of the title, it is just 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 campaign is complete and balanced. Trailing non-numeric elements are ok, but nothing should appear ''before'' the numbers! ([[#Version Key Example|See Examples]])
+
=== version ===
 +
: Displayed to the right of the title, it is just 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 campaign is complete and balanced. Trailing non-numeric elements are ok, but nothing should appear ''before'' the numbers. This is necessary for the ''Update add-ons'' button to work correctly. ([[#Version Key Examples|See Examples]])
  
* '''author''': Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the campaign you should list all of their names and perhaps describe what each person was responsible for.
+
=== author ===
 +
: Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the campaign you should list all of their names and perhaps describe what each person was responsible for.
  
* '''passphrase''': Not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.
+
=== passphrase ===
 +
: Not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.
  
* '''description''': Is not displayed in the client but it ''is'' visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and, for pre 1.0 versions, let people know how playable it is.
+
=== description ===
 +
: Is not displayed in the client but it ''is'' visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and, for pre 1.0 versions, let people know how playable it is.
  
* '''dependencies''': An optional list of dependencies. For example:
+
=== dependencies ===
  dependencies=Imperial_Era,Era_of_Myths
+
: An optional list of dependencies. ([[#Dependency Key Example|See Example]])
: This could be used when the two specified add-ons need to be installed for a campaign to work.
 
  
* '''translate''': If set to '''true''', the campaign will be sent to and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)
+
=== translate ===
 +
: If set to '''true''', the campaign will be sent to and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)
  
* '''type''': Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:
+
=== type ===
** ''campaign'': single player campaign.
+
: Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:
** ''scenario'': single player scenario.
 
** ''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.
 
** ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
 
  
* '''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 '''highly''' recommended that you provide one in case you need to be contacted about your addon.
+
:* ''campaign'': single player campaign.
 +
:* ''scenario'': single player scenario.
 +
:* ''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.
 +
:* media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
  
Example:
+
=== 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 ''highly'' recommended that you provide one in case you need to be contacted about your addon.
 +
 
 +
 
 +
The campaign server keeps track of some other information about uploaded campaigns, 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 addon 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 ===
 +
 
 +
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"
 
  title="My Campaign"
Line 59: Line 113:
 
  passphrase="This is like a password"
 
  passphrase="This is like a password"
 
  description="You get to kill a lot of bad guys. But only the first map is done."
 
  description="You get to kill a lot of bad guys. But only the first map is done."
  email="name@domain.ltd"
+
  email="name@example.com"
 
 
The campaign server keeps track of some other information about uploaded campaigns, 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]].
 
  
 
== See Also ==
 
== See Also ==
Line 68: Line 120:
 
* [[BuildingCampaignsThePBLFile]]
 
* [[BuildingCampaignsThePBLFile]]
 
* [[CampaignServerWML]]
 
* [[CampaignServerWML]]
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 23:24, 8 April 2009

[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, credits_group, criteria;

D:

damage, 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, found_item, for, foreach, 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, 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, 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 a campaign you have made, you need a .pbl file.

This is a file with name data/campaigns/campaign-name.pbl. Click here for an example of what we're talking about.

When you upload a campaign, the file data/campaigns/campaign-name.cfg and the directory data/campaigns/campaign-name/ will be published. Your campaign must be based entirely on these files. This may cause your campaign not to upload properly, for example, if you have custom campaign units in data/units/. Be aware that translations in the .pbl-files are not working, so don't mark these strings translateable.

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 on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see CampaignWML.) If the icon is a unit with magenta color, please use ImagePathFunctionWML to team-color it.

title

Displayed to the right of the icon, it is just text. It should usually be the same as the name of your campaign when it is played.

version

Displayed to the right of the title, it is just 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 campaign is complete and balanced. Trailing non-numeric elements are ok, but nothing should appear before the numbers. This is necessary for the Update add-ons button to work correctly. (See Examples)

author

Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the campaign you should list all of their names and perhaps describe what each person was responsible for.

passphrase

Not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.

description

Is not displayed in the client but it is visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and, for pre 1.0 versions, let people know how playable it is.

dependencies

An optional list of dependencies. (See Example)

translate

If set to true, the campaign will be sent to and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)

type

Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:
  • campaign: single player campaign.
  • scenario: single player scenario.
  • 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.
  • media: miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.

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 highly recommended that you provide one in case you need to be contacted about your addon.


The campaign server keeps track of some other information about uploaded campaigns, 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 addon 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

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"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"

See Also