Difference between revisions of "CampaignWML"

From The Battle for Wesnoth Wiki
(the [campaign] tag: add tags list)
(restructured, added examples for campaign menu and difficulty menu)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== the [campaign] tag ==
 
  
<!--
+
Each campaign consists of several scenarios.
 +
Those scenarios are described in their [[ScenarioWML|[scenario]]] tags.
 +
A '''[campaign]''' tag describes things related to the whole campaign, that is:
  
Dacyn and/or Invisible Philosopher -- please be careful
+
* how campaign appears in the game campaign menu
you don't reduce the signal-to-noise ratio on the WML pages
+
* electable difficulties
when editing!  Eg. knowing that a tag is translatable is _important_
+
* preprocessor symbol for campaign
for the 29 translations we have in progress. -- ott
+
* ID of the first scenario
 +
* campaign specific credits
  
-->
+
Please note that though scenario files are included from campaign files, the [scenario] tags do not appear inside of the [campaign] tags, but are typically included after them.
  
This tag describes a campaign, and is used for the "Campaign" menu
+
== The [campaign] tag ==
in the title screen.
+
 
 +
Campaign menu attributes:
 +
 
 +
* ''rank'' -- order of campaign in the campaign selection menu
 +
* ''icon'' -- small campaign image in the campaign selection menu
 +
* ''name'' -- (translatable) campaign name in the campaign selection menu
 +
* ''description'' -- (translatable) campaign description in the information pane of the campaign selection menu
 +
* ''image'' -- larger campaign image in the information pane of the campaign selection menu
 +
 
 +
Difficulty attributes:
 +
 
 +
* ''difficulties'' -- comma-separated list of preprocessor symbols
 +
* ''difficulty_descriptions'' -- menu of difficulties
 +
 
 +
Preprocessor attribute:
  
The '''[campaign]''' tag has the following attibutes:
 
* ''icon'' the image displayed in the campaign selection menu
 
* ''name'' (translatable) name displayed in the campaign selection menu
 
* ''image'' the image shown in the information pane when this campaign is selected in the campaign selection menu
 
* ''description'' (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
 
 
* ''define''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''.
 
* ''define''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''.
* ''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 [[UtilWML]]) 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.
+
 
* ''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.
+
First scenario attribute:
 +
 
 
* ''first_scenario'' the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]
 
* ''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 10 to 50; if you specify this, it should not be less than 51.
+
 
 +
Campaign credits subtag:
 +
 
 
* '''[about]''' {{DevFeature}} inserts your own credits into the game's list of credits. The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs.  There can be any number of '''[about]''' tags inside a '''[campaign]''' tag. The '''[about]''' tag has the following keys:
 
* '''[about]''' {{DevFeature}} inserts your own credits into the game's list of credits. The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs.  There can be any number of '''[about]''' tags inside a '''[campaign]''' tag. The '''[about]''' tag has the following keys:
 
** ''title'' (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
 
** ''title'' (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
 
** ''text'' (translatable, but you probably won't want to make it such) smaller text intended for the names of developers
 
** ''text'' (translatable, but you probably won't want to make it such) smaller text intended for the names of developers
  
The following keys of '''[campaign]''' are obsolete and have no effect:
+
Obsolete attributes: (do not use them)
* ''id'' the internationalization key for the campaign
+
 
 +
* ''id'' -- the internationalization key for the campaign
 +
 
 +
=== Campaign selection menu ===
 +
 
 +
Campaign selection menu displays a list of mainline and user-contributed campaigns.
 +
Campaigns are ordered by their ''rank'' attribute (lower to higher, unranked in the end).
 +
Mainline campaigns use multiples of 10 from 10 to 50.
 +
Your campaign's rank should be at least 51; but you do not have to specify it.
 +
 
 +
In the left part of dialog the ''icon'' and ''name'' of campaign are displayed.
 +
When user selects a campaign, the ''description'' and ''image'' are displayed in the right part.
 +
For example if [campaign] tag looks like this:
 +
 
 +
[campaign]
 +
  icon=small.png
 +
  name= _"My Campaign"
 +
  description= _"Hero goes somewhere and does something."
 +
  image=large.png
 +
  #...
 +
[/campaign]
 +
 
 +
Then the campaign selection menu will look like this:
 +
 
 +
+------------------------------+---------------------+
 +
| Select a campaign:          |                    |
 +
| [.....] Heir to the Throne  | Hero goes somewhere |
 +
| [.....] Son of the Black Eye | and does something. |
 +
| [.....] Eastern Invasion    |    [ large ]      |
 +
| [.....] The Rise of Wesnoth  |    [  .png ]      |
 +
| [small] My Campaign          |                [OK] |
 +
+------------------------------+---------------------+
 +
 
 +
=== Difficulty menu ===
 +
 
 +
From campaign author's view, "difficulty" is a preprocessor symbol, which can be used in scenario script to make gameplay easier or harder.
 +
This is typically done by making difficulty-dependent turn limits, starting gold for enemies, recruiting lists for enemies, AI commands,... but it can be anything.
 +
Exactly one on difficulty symbols is defined during campaign.
 +
 
 +
Using difficulties in campaign in optional.
 +
It is recommend to use standard symbols "EASY", "NORMAL", "HARD", because a few standard macros use them (file "utils.cfg"; see [[UtilWML]]).
 +
The ''difficulties'' attribute is a comma-separated list of preprocessor symbols to be defined.
 +
These symbols are used internally, and are never displayed to player.
 +
(It means that campaign author can use the symbols "EASY", "NORMAL", "HARD", even if the selection box contain different names, e.g. "Hard", "Very hard", "Nightmare".)
 +
The ''difficulty_descriptions'' is a formatted string that is best created using macros "MENU_IMG_TXT" and "MENU_IMG_TXT2" like this:
 +
 
 +
[campaign]
 +
  #...
 +
  difficulties=EASY,NORMAL,HARD
 +
  difficulty_descriptions= {MENU_IMG_TXT2 elvish-fighter.png  _"Fighter"  _"(easiest)"} + ";"
 +
                    + "*" + {MENU_IMG_TXT  elvish-hero.png    _"Hero"                } + ";"
 +
                          + {MENU_IMG_TXT2 elvish-champion.png _"Champion" _"(hardest)"}
 +
  #...
 +
[/campaign]
 +
 
 +
The semicolon ";" separates items in menu, and the asterisk "*" specifies the default value (see [[DescriptionWML]]).
 +
Number of rows in ''difficulty_descriptions'' must be the same as number of symbols in ''difficulties''.
 +
The difficulty menu will look like this:
 +
 
 +
+-------------------------------+
 +
| Choose a difficulty:          |
 +
| [fighter.] Fighter  (easiest) |
 +
| [hero.png] Hero              |
 +
| [champion] Champion (hardest) |
 +
+-------------------------------+
  
 
== See Also ==
 
== See Also ==
Line 37: Line 115:
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 
* [[PblWML]]
 
* [[PblWML]]
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 14:51, 21 March 2006

[edit]WML Tags

A:

abilities, about, add_ai_behavior, advance, 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, attack_anim, attacks, avoid;

B:

base_unit, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_range, command (action, replay), continue, 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, era, event, 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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, 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), illuminates, image, 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, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, 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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, set_menu_item), show_objectives, side, skirmisher, 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_type, store_unit_type_ids, store_villages, story, swarm, switch, sync_variable;

T:

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

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;

Each campaign consists of several scenarios. Those scenarios are described in their [scenario] tags. A [campaign] tag describes things related to the whole campaign, that is:

  • how campaign appears in the game campaign menu
  • electable difficulties
  • preprocessor symbol for campaign
  • ID of the first scenario
  • campaign specific credits

Please note that though scenario files are included from campaign files, the [scenario] tags do not appear inside of the [campaign] tags, but are typically included after them.

The [campaign] tag

Campaign menu attributes:

  • rank -- order of campaign in the campaign selection menu
  • icon -- small campaign image in the campaign selection menu
  • name -- (translatable) campaign name in the campaign selection menu
  • description -- (translatable) campaign description in the information pane of the campaign selection menu
  • image -- larger campaign image in the information pane of the campaign selection menu

Difficulty attributes:

  • difficulties -- comma-separated list of preprocessor symbols
  • difficulty_descriptions -- menu of difficulties

Preprocessor attribute:

  • define=CAMPAIGN_SYMBOL when this campaign is started, the preprocessor symbol CAMPAIGN_SYMBOL will be defined. See #ifdef in PreprocessorRef for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags [campaign] and [binary_path] (see BinaryPathWML) should go outside of #ifdef CAMPAIGN_SYMBOL.

First scenario attribute:

  • first_scenario the ID of the first scenario in the campaign; see id in ScenarioWML

Campaign credits subtag:

  • [about] Template:DevFeature inserts your own credits into the game's list of credits. The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of [about] tags inside a [campaign] tag. The [about] tag has the following keys:
    • title (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
    • text (translatable, but you probably won't want to make it such) smaller text intended for the names of developers

Obsolete attributes: (do not use them)

  • id -- the internationalization key for the campaign

Campaign selection menu

Campaign selection menu displays a list of mainline and user-contributed campaigns. Campaigns are ordered by their rank attribute (lower to higher, unranked in the end). Mainline campaigns use multiples of 10 from 10 to 50. Your campaign's rank should be at least 51; but you do not have to specify it.

In the left part of dialog the icon and name of campaign are displayed. When user selects a campaign, the description and image are displayed in the right part. For example if [campaign] tag looks like this:

[campaign]
  icon=small.png
  name= _"My Campaign"
  description= _"Hero goes somewhere and does something."
  image=large.png
  #...
[/campaign]

Then the campaign selection menu will look like this:

+------------------------------+---------------------+
| Select a campaign:           |                     |
| [.....] Heir to the Throne   | Hero goes somewhere |
| [.....] Son of the Black Eye | and does something. |
| [.....] Eastern Invasion     |     [ large ]       |
| [.....] The Rise of Wesnoth  |     [  .png ]       |
| [small] My Campaign          |                [OK] |
+------------------------------+---------------------+

Difficulty menu

From campaign author's view, "difficulty" is a preprocessor symbol, which can be used in scenario script to make gameplay easier or harder. This is typically done by making difficulty-dependent turn limits, starting gold for enemies, recruiting lists for enemies, AI commands,... but it can be anything. Exactly one on difficulty symbols is defined during campaign.

Using difficulties in campaign in optional. It is recommend to use standard symbols "EASY", "NORMAL", "HARD", because a few standard macros use them (file "utils.cfg"; see UtilWML). The difficulties attribute is a comma-separated list of preprocessor symbols to be defined. These symbols are used internally, and are never displayed to player. (It means that campaign author can use the symbols "EASY", "NORMAL", "HARD", even if the selection box contain different names, e.g. "Hard", "Very hard", "Nightmare".) The difficulty_descriptions is a formatted string that is best created using macros "MENU_IMG_TXT" and "MENU_IMG_TXT2" like this:

[campaign]
  #...
  difficulties=EASY,NORMAL,HARD
  difficulty_descriptions= {MENU_IMG_TXT2 elvish-fighter.png  _"Fighter"  _"(easiest)"} + ";"
                   + "*" + {MENU_IMG_TXT  elvish-hero.png     _"Hero"                 } + ";"
                         + {MENU_IMG_TXT2 elvish-champion.png _"Champion" _"(hardest)"}
  #...
[/campaign]

The semicolon ";" separates items in menu, and the asterisk "*" specifies the default value (see DescriptionWML). Number of rows in difficulty_descriptions must be the same as number of symbols in difficulties. The difficulty menu will look like this:

+-------------------------------+
| Choose a difficulty:          |
| [fighter.] Fighter  (easiest) |
| [hero.png] Hero               |
| [champion] Champion (hardest) |
+-------------------------------+

See Also