Difference between revisions of "CampaignWML"

From The Battle for Wesnoth Wiki
m (use 1.14 Template, which exists by now)
(2 intermediate revisions by 2 users not shown)
Line 44: Line 44:
 
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}
 
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}
 
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''
 
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''
;ENABLE_WARMASTER {{DevFeature1.13|11}}
+
;ENABLE_PARAGON {{DevFeature1.15|1}}
:allows the advancement ''Dune Blademaster'' -> ''Dune Warmaster''
+
:allows the advancement ''Dune Blademaster'' -> ''Dune Paragon''
:'''Note''': This macro doesn't work for 1.15.0 and later as Dunefolk were revamped in 1.15.0. (In particular, the Warmaster was renamed Paragon)
 
 
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}
 
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}
 
:allows the advancement ''Wose'' -> ''Wose Shaman''
 
:allows the advancement ''Wose'' -> ''Wose Shaman''
Line 62: Line 61:
 
* '''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]]
 
* '''[options]''':  {{DevFeature1.13|1}} Allows configuration options to be displayed to  the user, see [[OptionWML]]
 
* '''[options]''':  {{DevFeature1.13|1}} Allows configuration options to be displayed to  the user, see [[OptionWML]]
* '''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 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400.  (Note: This replaces an older convention that topped out at 50.) '''''(Version 1.14.6 and later only)''''' 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 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
+
* '''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 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400.  (Note: This replaces an older convention that topped out at 50.) {{DevFeature1.14|6}} 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 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
 
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
 
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
 
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.
 
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.
Line 80: Line 79:
 
== Campaign credits ==
 
== Campaign 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, but none of them will display credits if there is no "id" key present inside [campaign] (see above). The '''[about]''' tag has the following keys:
+
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 which is displayed before the contributor names
 
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names

Revision as of 03:23, 20 January 2020

[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;


This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.

The [campaign] Tag

The following keys and tags are recognized in [campaign] tags:

  • id: the internal campaign identifier used to classify saved games
  • icon: the image displayed in the campaign selection menu
  • name: (translatable) name displayed in the campaign selection menu
  • abbrev: (translatable) abbreviation used as a prefix for savefile names made from this campaign
  • image: the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)
  • description: (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
  • description_alignment: (Version 1.13.3 and later only) The text alignment of the description. Choose between "left" (default), "center", or "right".
  • type: campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".
  • 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. This symbol will be defined before any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the #ifdef CAMPAIGN_SYMBOL block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.
  • extra_defines: a comma(,) separated list of preprocessor symbols. Those symbols will be defined before any .cfg is preprocessed. Currently supported extra_defines are:
    ENABLE_ARMAGEDDON_DRAKE
    allows the advancement Inferno Drake -> Armageddon Drake
    ENABLE_DWARVISH_ARCANISTER
    allows the advancement Dwarvish Runemaster -> Dwarvish Arcanister
    ENABLE_DWARVISH_RUNESMITH
    allows the advancement Dwarvish Fighter -> Dwarvish Runesmith
    DISABLE_GRAND_MARSHAL
    disallows the advancement General -> Grand Marshal
    ENABLE_ANCIENT_LICH
    allows the advancement Lich -> Ancient Lich
    ENABLE_DEATH_KNIGHT
    allows the advancement Revenant -> Death Knight'
    ENABLE_TROLL_SHAMAN
    allows the advancement Troll Whelp -> Troll Shaman
    ENABLE_WOLF_ADVANCEMENT
    allows the advancements Wolf -> Great Wolf -> Direwolf
    ENABLE_NIGHTBLADE (Version 1.13.0 and later only)
    allows the advancement Orcish Slayer -> Orcish Nightblade
    ENABLE_PARAGON (Version 1.15.1 and later only)
    allows the advancement Dune Blademaster -> Dune Paragon
    ENABLE_WOSE_SHAMAN (Version 1.15.1 and later only)
    allows the advancement Wose -> Wose Shaman
  • 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 Macro Reference) 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. (Version 1.13.2 and later only) This key has been deprecated in favor of [difficulty] define=.
  • 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. (Version 1.13.2 and later only) This key has been deprecated in favor of [difficulty] define=
  • [difficulty]: (Version 1.13.2 and later only) specifies a single campaign difficulty. The following keys are accepted:
    • define: the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old difficulties list.
    • image: the image to display for this difficulty in the selection menu
    • label: a flavor label describing this difficulty. Displayed second after the image
    • description: a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.
    • default: whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.
    • auto_markup: (Version 1.15.0 and later only) By default, the description is shown in small, gray text within parentheses. Setting auto_markup=no disables these, so no markup will be applied implicitly. Any markup in description will be honored regardless of this setting.
  • allow_difficulty_change: Allows difficulty switching during an ongoing campaign. Default:yes
  • first_scenario: the ID of the first scenario in the campaign; see id in ScenarioWML
  • [options]: (Version 1.13.1 and later only) Allows configuration options to be displayed to the user, see OptionWML
  • 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 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) (Version 1.14.6 and later only) 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 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.
  • start_year: a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example 20 BW, 20 YW, 20 BF or 20 AF. In Wesnoth 1.14, this is the only place in which this date-parsing is used.
  • end_year: a string that helps determine the order of campaigns when two campaigns have the same start_year. Ignored if start_year is not set.
  • year: shortcut for specifying both start_year and end_year, for campaigns that happen inside a single calendar year. Ignored if start_year is given.
  • [about]: inserts your own credits into the game's list of credits. See below for syntax.
  • end_credits: Whether to display the credits screen at the end of the campaign. Defaults to yes.
  • end_text: (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
  • end_text_duration: Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time end_text is displayed on screen. Defaults to 3500.
  • [event]: (Version 1.13.2 and later only) events placed here will be automatically inserted into all scenarios of the campaign.

The following keys are additionally recognized in multiplayer:

  • min_players: Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.
  • max_players: Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either min_players or 2, whichever is higher.
  • allow_era_choice: Whether to hide era selection and use a default one when creating a game. Defaults to yes.
  • require_campaign: Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.

Campaign 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 which is displayed before the contributor names
  • [entry]: Contains information about a single contributor. Only the name key will be used in-game, the other three keys are for display on the Credits page (note: the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)
    • name: The name of the contributor
    • comment: Optional short note about what that person did
    • email: Optional email address
    • wikiuser: Optional, the user name on the wiki

See Also