Difference between revisions of "EraWML"

From The Battle for Wesnoth Wiki
m (the [era] top level tag)
(addon_min_version clarification based on Soliton's explanation)
(32 intermediate revisions by 18 users not shown)
Line 1: Line 1:
== the [era] top level tag ==
+
{{WML Tags}}
 +
== The [era] top level tag ==
  
This tag describes one era.
+
This tag describes one era. An era is a set of teams to play in multiplayer.
An era is a set of teams to play in multiplayer.
+
 
In the multiplayer game selector screen,
+
In the multiplayer game creation screen, an era is chosen by the host by the 'Era' option button.
an era is chosen by the host by the 'Era' option button.
 
  
 
The following key/tags are recognized for '''[era]'''
 
The following key/tags are recognized for '''[era]'''
* ''name'' displayed name of the era.
+
* '''id''': ID of the era - must be unique. No gameplay effect
* ''id'' ID of the era - must be unique. No gameplay effect
+
* '''name''': displayed name of the era.
* '''[multiplayer_side]''' a faction in the era.
+
* '''description''': a short description of the era.
This tag contains many of the same keys as a [side] tag
+
* <span id="require_era">'''require_era'''</span>: whether clients are required to have this era installed beforehand to be allowed join a game using this era. Possible values 'yes' (the default) and 'no'.
(A description of the [side] tag can be found in [[SideWML]]).
+
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
When a multiplayer game is played, then the [side] tag for the scenario
+
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this era. Cannot be used in parallel with allow_scenario.
is merged with the keys(currently, not tags)
+
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
of the [multiplayer_side] tag of the faction which the side chose.
+
* '''allow_modification''': same as allow_scenario, but for modifications.
** ''name'' a description (see [[DescriptionWML]])
+
* '''disallow_modification''': same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
that is displayed as the option for selecting that faction.
+
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
** ''id'' faction ID - must be unique to your era. No gameplay effect
+
* '''force_modification''': a list of modification ids. The specified modifications must be enabled to play this era.
** ''leader'' a list of unit types.
+
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. If ''addon_min_version'' is not explicitly specified, it means compatible only with the same version. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
When this faction is chosen, the side can choose
+
* '''hide_help''': {{DevFeature1.13|0}} whether this era should show up in the help browser or not. Default no.
any of these unit types to be the side's leader (i.e. "Choose your Leader").
+
* '''[multiplayer_side]''': a faction in the era. This tag contains many of the same keys as a [side] tag (A description of the [side] tag can be found in [[SideWML]]). When a multiplayer game is played, then the [side] tag for the scenario is merged with the keys(currently, not tags) of the [multiplayer_side] tag of the faction which the side chose.
They will also have the option of having one of these types being chosen randomly.
+
** '''id''': faction ID - must be unique to your era. No gameplay effect
** ''random_leader'' 1.1+SVN : if a ''random_leader'' (list of types) is present, it would use this list to instead to choose a random leader. If not it would use ''leader''
+
** '''name''': a description that Wesnoth displays as the option selecting that faction; see [[DescriptionWML]]. Any image in this description will ''not'' use the team color. This key is used for sorting factions in era. For manual sorting see https://github.com/wesnoth/wesnoth/issues/3177.
** ''random_faction'' default 'no'.
+
** '''image''': an image to display in the option. This image will use the team color.
If 'yes', then when this faction is chosen,
+
** '''flag_rgb''': often set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]
another faction will be randomly chosen instead.
+
** '''leader''': a list of unit types. Must be present. When this faction is chosen, the side can choose any of these unit types to be the side's leader (i.e. "Choose your Leader"). They will also have the option of having one of these types being chosen randomly.
The leader will also be chosen randomly.
+
** '''random_leader''': if this list of types is present, it would use this list to instead to choose a random leader. If not it would use '''leader'''
** ''terrain_liked'' an unseparated list of terrains (see [[TerrainLettersWML]]).
+
** '''random_faction''': default 'no'. If 'yes', then when this faction is chosen, another non random faction will be randomly chosen instead. The leader will also be chosen randomly. All random_faction=yes factions are sorted before other factions.
On random maps, these terrains will determine which keep the side is assigned,
+
** '''choices''': Empty by default. If non-empty and the faction has '''random_faction=yes''', it is the list of the IDs of the non random factions that will be choosen randomly. If empty, any faction can be chosen.
attempting to put it near the listed terrains.
+
** '''except''': Empty by default. If the faction has random_faction=yes, it is the list of the IDs of the non random factions that will not be choosen randomly.
 +
** '''type''': the unit type of the default leader for the side. This must be present. 'random' is a valid value here and will cause a random leader choice by default.
 +
** '''recruit''': a comma-separated list of unit types this faction can recruit.
 +
** '''extra_recruit''': a comma-separated list of unit types appended to the leader recruitlist (see [[SingleUnitWML]]).
 +
** '''terrain_liked''': an unseparated list of terrains (see [[TerrainCodesWML]]). On random maps, these terrains will determine which keep the side is assigned, attempting to put it near the listed terrains.
 +
** '''description''': a short description of the faction, displayed in the help browser.
 +
* '''[event]''': any [event]s written inside the [era] tag will get included into scenarios that are played using this era. See [[EventWML]].
 +
* '''[lua]''': any [lua] children written inside the [era] tag will get included into scenarios that are played using this era.
 +
* '''[options]''': custom options. See [[OptionWML]] for details.
 +
* '''[ai]''': See [[AiWML]] for details.
  
 
== See Also ==
 
== See Also ==
Line 35: Line 44:
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 
* [[SideWML]]
 
* [[SideWML]]
 +
 +
 +
[[Category: WML Reference]]

Revision as of 21:06, 26 April 2021

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

The [era] top level tag

This tag describes one era. An era is a set of teams to play in multiplayer.

In the multiplayer game creation screen, an era is chosen by the host by the 'Era' option button.

The following key/tags are recognized for [era]

  • id: ID of the era - must be unique. No gameplay effect
  • name: displayed name of the era.
  • description: a short description of the era.
  • require_era: whether clients are required to have this era installed beforehand to be allowed join a game using this era. Possible values 'yes' (the default) and 'no'.
  • allow_scenario: a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
  • disallow_scenario: a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this era. Cannot be used in parallel with allow_scenario.
  • ignore_incompatible_scenario: a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
  • allow_modification: same as allow_scenario, but for modifications.
  • disallow_modification: same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
  • ignore_incompatible_modification: same as ignore_incompatible_scenario, but for modifications.
  • force_modification: a list of modification ids. The specified modifications must be enabled to play this era.
  • addon_min_version: (Version 1.13.0 and later only) the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in PblWML. If addon_min_version is not explicitly specified, it means compatible only with the same version. Clients in multiplayer must have add-on versions agreeing with the addon_min_versions of eachothers content in order to play, and will be prompted to update otherwise.
  • hide_help: (Version 1.13.0 and later only) whether this era should show up in the help browser or not. Default no.
  • [multiplayer_side]: a faction in the era. This tag contains many of the same keys as a [side] tag (A description of the [side] tag can be found in SideWML). When a multiplayer game is played, then the [side] tag for the scenario is merged with the keys(currently, not tags) of the [multiplayer_side] tag of the faction which the side chose.
    • id: faction ID - must be unique to your era. No gameplay effect
    • name: a description that Wesnoth displays as the option selecting that faction; see DescriptionWML. Any image in this description will not use the team color. This key is used for sorting factions in era. For manual sorting see https://github.com/wesnoth/wesnoth/issues/3177.
    • image: an image to display in the option. This image will use the team color.
    • flag_rgb: often set by MAGENTA_IS_THE_TEAM_COLOR
    • leader: a list of unit types. Must be present. When this faction is chosen, the side can choose any of these unit types to be the side's leader (i.e. "Choose your Leader"). They will also have the option of having one of these types being chosen randomly.
    • random_leader: if this list of types is present, it would use this list to instead to choose a random leader. If not it would use leader
    • random_faction: default 'no'. If 'yes', then when this faction is chosen, another non random faction will be randomly chosen instead. The leader will also be chosen randomly. All random_faction=yes factions are sorted before other factions.
    • choices: Empty by default. If non-empty and the faction has random_faction=yes, it is the list of the IDs of the non random factions that will be choosen randomly. If empty, any faction can be chosen.
    • except: Empty by default. If the faction has random_faction=yes, it is the list of the IDs of the non random factions that will not be choosen randomly.
    • type: the unit type of the default leader for the side. This must be present. 'random' is a valid value here and will cause a random leader choice by default.
    • recruit: a comma-separated list of unit types this faction can recruit.
    • extra_recruit: a comma-separated list of unit types appended to the leader recruitlist (see SingleUnitWML).
    • terrain_liked: an unseparated list of terrains (see TerrainCodesWML). On random maps, these terrains will determine which keep the side is assigned, attempting to put it near the listed terrains.
    • description: a short description of the faction, displayed in the help browser.
  • [event]: any [event]s written inside the [era] tag will get included into scenarios that are played using this era. See EventWML.
  • [lua]: any [lua] children written inside the [era] tag will get included into scenarios that are played using this era.
  • [options]: custom options. See OptionWML for details.
  • [ai]: See AiWML for details.

See Also